Gugu-web：AI Agent 工具实践指南

工作中遇到相关需求时，Gugu-web值得先读说明，因为它主要用于Not another chatbox.Agent 工作空间，看板、日历、笔记和文件都能直接操作｜飞书 · QQ · 微信 | BYOK。在网页与浏览器自动化场景里，常见问题是登录状态、页面变化和失败恢复往往不稳定，这正是评估时需要盯住的地方。我的评估方法是选择一个权限清楚的网页流程做端到端短测，然后检查会话保持、元素定位、错误恢复和工件留存是否与文档一致。我会把它列入需要可观测网页自动化流程的开发者的候选清单，而不是仅凭项目介绍直接纳入生产。

咕咕

Agent UI，必须先有 UI。

咕咕的想法：把散落的看板、日历、笔记、文件和画布放到一起，让用户和 Agent 在同一个地方做事。

这是一个个人的 Vibe Coding 项目，欢迎通过 Issue 和 PR 参与改进。

中文 ｜ English ｜ 快速部署 ｜ 在线预览

能做什么

为什么做咕咕？

本人原本是一名插画师，以前经常遇到一种情况：和客户约好的稿子忘了记录，后来忙着忙着也就忘了，平时也有一些文件管理上的苦恼。

后来有段时间尝试了下 QwenPaw，发现 Agent 在记录项目、整理文档和想法上效率很高。但找了一圈，没有发现一个顺手的 UI：Agent 记录的大量文档，最后还是需要自己去本地找，或者让 Agent 发回来再自己整理。

咕咕一开始只有项目管理功能，但后来慢慢加上了交互 Runtime、文件系统、看板、画布、Shell 和沙盒。现在它已经比最初大了很多，相信这些功能也不只是我一个人用得到。

如果最后还是一个聊天框，为什么要叫 Agent UI？

欢迎试用，也欢迎前往 www.gugugu.site 在线体验，或者按照下方的说明在本地部署。不过服务器能力有限，在线体验时可能会没那么流畅。最后，也欢迎提 Issue 和 PR。

功能预览

  <h3>看板</h3>

</td>
<td width="50%" valign="top">
  
  <h3>文件系统</h3>

</td>

  <h3>画布</h3>

</td>
<td width="50%" valign="top">
  
  <h3>Admin</h3>

</td>

  <h3>LoopScope</h3>

</td>

咕咕对话

  <h3>管理日程</h3>

</td>
<td width="25%" valign="top">
  
  <h3>记录想法</h3>

</td>
<td width="25%" valign="top">
  
  <h3>即时通讯</h3>

</td>
<td width="25%" valign="top">
  
  <h3>多平台支持</h3>

</td>

工具组概览

咕咕的工具按能力组织成工具组。Agent 会根据任务选择合适的工具组合，用户不需要记住具体工具名称。

快速开始

前置要求

• Docker 20+ 和 Docker Compose v2.20+
• 模型提供商 API Key（BYOK）
• 首次启动需要访问 Docker Hub 等镜像仓库；默认一体化镜像内置 PostgreSQL 和 Redis

国内网络环境

国内用户拉取默认 Compose 的一体化镜像、进行源码开发或安装依赖时，可以按需使用代理或镜像源。默认 Compose 使用预构建的一体化镜像，不需要先安装 Python 或 Node 依赖。

# pnpm / npm 依赖
corepack pnpm install --registry=https://registry.npmmirror.com

# 本地安装 Python 依赖
python -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r backend/requirements.txt

# Dev Compose 重新构建镜像时使用清华 PyPI 镜像
PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple 
  docker compose -f docker-compose.dev.yml up -d --build

镜像源只影响当前命令；也可以根据网络情况改用官方源或其他可信镜像。

一键部署（推荐，linux/amd64）

mkdir -p gugu && cd gugu
curl -fsSL https://raw.githubusercontent.com/Coffeiz/Gugu-web/main/docker-compose.yml -o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/Coffeiz/Gugu-web/main/.env.example -o .env.example
cp .env.example .env
# 编辑 .env，至少填写 GUGU_DB_PASSWORD；SECRET_KEY 留空时首次启动自动生成并持久化
# 模型配置可在启动后通过 Admin 页面设置；未设置管理员密码时首次启动自动生成
# 用户数据目录默认在当前部署目录的 Gugu-data，Compose 首次启动会自动创建。
# 如使用自定义绝对路径，写入 .env：GUGU_DATA_HOST_DIR=/srv/gugu-data
docker compose up -d

无需克隆源码：部署目录只需保留 docker-compose.yml 和自己的 .env。Compose 会自动从 Docker Hub 拉取应用镜像及所需服务镜像。fnOS 等 NAS 面板支持直接粘贴 YAML 时，可使用快速部署指南中的 Compose 示例。

基础变量可以这样配置：

# 根目录 .env：默认 Compose 配置
# SECRET_KEY 可省略；首次启动自动生成并保存到 Gugu-data/.env
GUGU_DB_PASSWORD=请替换为数据库密码
GUGU_WEB_IMAGE=coffeiz/gugu-web:latest

# 可选管理员配置；不填写 ADMIN_PASSWORD 时由首次启动生成并保存
ADMIN_USERNAME=admin
ADMIN_PASSWORD=请替换为管理员密码
# 用户可访问的公开站点根地址，用于邮箱验证和密码重置链接
GUGU_PUBLIC_APP_URL=http://localhost:9595

如果通过域名或 Nginx 反向代理部署，请将 GUGU_PUBLIC_APP_URL 改为用户实际访问的完整地址，例如 https://gugu.example.com。Nginx 负责统一入口和转发，后端使用同一配置生成外部链接，不会把 localhost:8001 等容器内部地址写入邮件。

默认一体化 Compose 从根目录 .env 读取部署参数，模型 Provider 和 API Key 可在启动后通过 Admin 页面配置；完整参数和配置位置见部署指南。

默认 Compose 使用统一的 Gugu 应用镜像，包含前端、Nginx、Uvicorn、worker、IM gateway、PostgreSQL 和 Redis；SearXNG 由 Compose 中的独立服务提供。部署使用本地部署目录中的 docker-compose.yml，数据挂载由该编排文件固定管理。prod/dev Compose 用于需要分开管理前后端的场景。详见快速部署指南。

启动后访问：

• 咕咕：http://localhost:9595
• Admin：http://localhost:9595/admin/

首次运行会初始化数据库并执行迁移。未设置 ADMIN_PASSWORD 时会生成随机密码并保存到 Gugu-data/.env，终端只打印一次；不会使用公开默认密码。

集成 Compose 与单容器镜像使用 app 内部的 Rootless Docker 和随镜像打包的执行 runtime，不需要部署独立 sandboxd 或将宿主 Docker Socket 交给 app。集成 app 外层需以 privileged 模式运行；单容器部署在 fnOS 等面板中启用“使用高权限执行容器”。该模式面向可信个人单用户，不适用于多租户、公网或业务服务器。分体生产 Compose 继续使用独立 Rootless sandboxd；详细部署边界与配置见快速部署指南。

开发者需要源码挂载和 Vite 开发服务器时，使用 Dev Compose：

docker compose -f docker-compose.dev.yml up -d

开发环境还可以访问：

• Backend API 文档：http://localhost:8000/docs
• LoopScope Collector：http://localhost:4320

LoopScope 需要先登录咕咕，访问咕咕的 /dev 页面，再点击页面里的 LoopScope 入口；这样才能带上当前账号上下文，看到自己账号的数据。直接打开 Collector 地址不会正常显示对应数据。

配置

README 只保留配置索引，完整变量和运行规则将在 docs/configuration.md 中整理。

部署细节见 简版部署指南，复杂的生产排障见 运维部署文档。

Workspace

咕咕不是把项目、日历、文件和笔记分散成几个孤立页面，而是把它们放在同一个持续使用的工作空间里。用户和 Agent 看到的是同一套数据，也可以直接在这套数据上继续操作。

交互数据采用“本地即时反馈、服务端最终收敛”的同步原则。统一的 InteractionSync 负责协调本地 mutation、服务端响应和跨标签页实时事件，避免各业务页面重复编排 optimistic 状态。具体边界和实施状态见 本地交互与服务端同步一致性 PRD。

项目、阶段、任务、日历、提醒、文件、笔记和无限画布彼此关联。可以从项目找到文件和截止日期，也可以把项目、文件和想法拖到画布上继续整理。

  <h3>项目看板</h3>

</td>
<td width="50%" valign="top">
  
  <h3>日历</h3>

</td>

  <h3>笔记与想法</h3>

</td>
<td width="50%" valign="top">
  
  <h3>画布与关系</h3>

</td>

  <h3>文件系统</h3>

</td>
<td width="50%" valign="top">
  
  <h3>定时任务</h3>

</td>

看板支持跨列拖拽和排序，文件可以在不同容器之间移动，画布支持自由落点和关系整理。复杂交互由独立的 gugu-interaction-runtime 驱动。Agent 创建的项目、任务、日历活动和文件会直接出现在工作空间里，用户在界面上的修改也会成为 Agent 后续可以继续使用的真实状态。

代理

咕咕的 Agent 可以读取和操作用户所见的数据与功能，拥有与用户等价的系统操作能力，不局限于聊天或某一项能力。

Channels

同一个 Agent Loop 可以从网页和即时通讯渠道进入，渠道只负责连接和消息适配，身份、会话、上下文、权限和工具仍由共享后端统一处理。

推荐优先使用 QQ。 目前 QQ 渠道经过了最多的适配和优化，在群聊、消息引用、流式回复、文件处理和交互控件方面支持最完整。

Agent Loop

Runtime 统一处理上下文、模型 Round、工具选择、工具执行和受控续轮。支持工具调用、联网搜索、定时任务、流式响应，以及 QQ、微信、飞书等即时通讯入口。相关设计见 Agent 文档 和 Agent Loop。

flowchart LR
    C[Web / QQ / 微信 / 飞书] --> A[Agent Loop]
    A --> X[上下文工程]
    X --> L[LLM 提供商]
    L --> A
    A --> T[工具和 Skills]
    T --> W[Workspace]
    A --> M[记忆系统]
    M --> X
    A --> O[LoopScope]

上下文工程

把系统提示、能力目录、对话历史、工具结果、Memory 和 RAG 组织成稳定、可恢复的上下文，并区分可缓存的稳定内容和每轮更新的动态内容。相关设计见上下文工程文档。

咕咕将一次 Agent 请求的上下文分成几个边界清晰的区域：稳定规则放在 system，会话级且可复用的能力和状态放在 snapshot，已封存的对话与工具往返放在 history，本轮新增内容由 batch 组织；只有确实需要提供商临时信息时才使用 dynamic tail。这样既方便多轮恢复，也能让稳定前缀参与提供商缓存。

这套架构的一个明确目标是：从第二轮对话开始保持可复用的稳定前缀。system、稳定 snapshot 和已封存的 history 按固定顺序组装；batch 会先稳定地并入当前请求，确认后再进入 history。system 开头只注入按用户时区计算的当前日期和星期（每天最多变化一次，不包含时分秒）；用户消息时间、RAG 结果、群聊身份和工具续轮等本轮事实进入 batch。普通 Web/IM 请求不再额外注入当前时间 dynamic tail。只有明确需要提供商专属临时信息的路径才使用 dynamic tail，避免每轮产生无意义的重复上下文。

这项设计在 2026-09-02 的连续会话复测中得到验证：4 个模型分别预热 1 轮后连续执行 20 个 case，8 组测试均完成且没有记录 history compaction。四个模型合计，简介模式的累计提供商输入比全量模式低 25.72%；但 MiniMax 因额外续轮较多，简介模式单独比全量模式高 3.98%，说明稳定前缀的收益还需要结合续轮次数判断。

缓存率与上下文稳定性

缓存率定义为 cache_read / provider_input，实际命中率仍由提供商的缓存策略决定，不能把架构保证的前缀稳定性等同于服务商的命中承诺。详见 Schema 模式复测报告。

flowchart LR
    S[system
人格 / policy / 稳定规则] --> C[Context Assembly]
    P[snapshot
会话状态 / Memory 摘要 / 工具目录] --> C
    H[history
已封存的对话与工具往返] --> C
    I[本轮用户输入与上下文] --> B[MessageBatch]
    H --> A[MessageArea]
    B --> A
    C --> R[固定上下文 + ProviderConversation]
    A --> R
    R --> L[LLM 提供商]
    T[定时任务当前时间] --> B
    L --> Q{是否需要工具续轮}
    Q -- 是 --> B
    Q -- 否 --> D[PersistenceDelta]
    A --> D
    D --> H2[事务持久化到 history]
    H2 --> H

每轮由统一组装器生成一个 MessageBatch，只承载 canonical 消息增量和分组元数据；追加后由 MessageArea 负责唯一的运行期顺序、来源和持久化策略。Provider 请求从 Area 的不可变快照生成 ProviderConversation，不会把 Provider wire 写回 Area；收尾阶段只将 Area 生成的 PersistenceDelta 事务性持久化。下一次请求仍从数据库恢复历史，而不是从 Provider wire 格式反推。

上下文的组装顺序保持稳定：system 提供跨会话规则，snapshot 放在 history 之前形成固定前缀，已封存的 history 后接当前 batch。普通 Web/IM 请求的消息时间、RAG 和群聊运行上下文都在 batch 内；定时任务的当前时间也通过 batch 注入。dynamic tail 只作为可选的提供商专属边界，新增消息始终插在它之前；因此工具续轮、压缩和跨提供商转换时都不会把临时信息误写进历史或打乱稳定前缀。

工具和 Skills

工具负责读取和修改工作空间，Skills 负责提供可复用的任务知识和操作流程。咕咕为工具和 Skills 制作了一套注册系统，可以快速注册、组织和接入新的能力；能力目录按需注入工具 Schema，在保持可用性的同时减少不必要的 Token 消耗。执行时仍由代码校验权限、参数和危险操作；在群聊中还会按群组、成员和发起者隔离数据与工具权限，避免同群成员互相越权访问。相关设计见工具与 Skill 文档。

在简介模式下，系统向模型注入全部已授权工具的 description_short 和自动生成的可用字段签名，同时注入当前可用 Skills 的短简介。业务工具需要更复杂的结构时，可通过 get_tool_schema 按需获取完整 Schema，实际操作时通过 call_tool 调用；Skills 通过 use_skill 后，系统才会读取 Skill 文档中注册并选择的工具，将这些工具的 Schema 注入后继续完成任务。当前默认使用全量模式。

正文编辑契约和工具 Schema 的详细约定见工具注册与开发文档。

Schema 模式取舍

咕咕目前保留两种工具 Schema 注入模式：

在 2026-09-02 的 4 个模型、5 个目标工具、每组预热 1 轮并连续测试 20 轮的复测中，简介模式的固定注入成本比全量模式少约 51.86%–54.13%；四个模型合计的 provider input 少 25.72%、总 Token 少 25.51%。本轮全量模式四个模型均为 20/20，简介模式为 16/20–20/20；MiniMax 因简介模式额外触发更多续轮，实际 input 比全量模式高 3.98%。这组数据用于说明两种模式的 Token 成本和准确率取舍；缓存率和稳定前缀属于上方上下文工程区域的缓存率与上下文稳定性。完整测试口径见 Schema 模式复测报告。

记忆系统

咕咕会在对话和任务完成后进行异步反思，把值得长期保留的信息整理为可复用的上下文。它不只是保存聊天记录，也会记住用户偏好、工作习惯、项目状态、重要约定、近期进展和经过确认的事实；临时闲聊、重复内容和不确定信息不会直接成为长期记忆。

每次 Agent Loop 开始时，系统会根据当前用户、会话和任务按需加载近期状态、相关长期记忆与检索结果，再交给上下文工程统一组织。Memory 负责结构化的个人上下文，Knowledge / RAG 负责从项目、文件、笔记和历史内容中检索相关知识，两者互相补充，而不是把全部历史内容一次性塞进模型上下文。

记忆、Knowledge 和 RAG 都遵循用户与工作空间隔离规则。群聊中会进一步区分群组、成员和消息发起者，只加载当前请求有权访问的记忆与知识，避免不同用户之间共享或串用私人上下文。相关设计见 Memory 与 Reflection 和 RAG 与 Knowledge。

可观测性

LoopScope 是咕咕 Agent 的开发观测和排障工具，用来还原一次请求实际经过的上下文、模型 Round、工具调用和输出链路，帮助定位“Agent 为什么这样做”和“哪一步变慢了”。它只记录和展示诊断信息，不参与工具执行、业务决策或运行状态修改；当前通过 /dev 进入咕咕账号对应的 LoopScope 工作区。

如何进入

1. 先登录咕咕。
2. 访问咕咕的 /dev 页面。
3. 在开发工具中选择 LoopScope，打开观测工作区。
4. 回到咕咕发送消息或执行操作，再在 LoopScope 中选择对应的 Session 查看 Run、Round、Tool 和上下文详情。

必须从已登录的咕咕 /dev 页面进入。这个入口会把当前账号的 API 地址和临时登录上下文通过浏览器 postMessage 传给 LoopScope；直接打开 4319 前端地址或 4320 Collector 地址，不会自动关联当前账号的数据。Collector 不可用时不会阻塞咕咕的回复、工具执行或消息落库。详细说明见 LoopScope 文档。

安全与隔离

咕咕的 Agent 可以读取和修改真实的项目、文件、日历与外部渠道，因此安全边界由数据归属、工具校验和执行环境共同保证，而不是只依赖模型自己遵守提示词。

用户与数据隔离

• 业务资源通过统一的所有权查询入口校验用户归属；不存在的资源和不属于当前用户的资源对外统一表现为“未找到”，避免资源枚举。
• 项目、文件、笔记、记忆、Knowledge / RAG 和工作空间按用户及工作空间隔离。
• QQ、微信、飞书等渠道会保留平台用户、群组和发起者身份；群聊中的记忆、知识、工具权限和工作区访问会按群组与成员范围进一步限制。

Agent 工具安全

• 工具执行前由 Runtime 统一进行 Schema、参数、用户归属、权限和运行环境校验。
• 写入和删除不是同一等级：不可逆操作声明为 destructive，并通过确认交互和短期确认 Token 拦截；未确认时不会直接执行。
• 工具和 Skills 的可发现、可注入、可调用、可执行是不同状态，最终权限以服务端 dispatch 校验为准，不能仅凭模型收到的 Schema 判断已经获得访问权。

Shell 沙盒

• Shell 默认使用 sandbox 范围和 network=none；范围在每次调用开始时固定，绑定工作区时只能访问该工作区对应目录。
• 沙盒执行通过 sandboxd 和 Docker 承载，包含目录边界、配额、生命周期和执行超时控制；sandboxd 不可用时不会回退到本机执行。
• 所有用户沙盒共用项目维护的固定运行时镜像，预装 Python、Node/npm、ffmpeg、Git、curl、jq 和 Bash；用户工作区仍按用户独立挂载，不共享文件和进程。
• system 范围是明确开启的宿主机执行能力，不属于默认沙盒；危险命令、宿主机范围和受控 egress 网络都需要额外配置或确认。
• 受控 egress 只允许沙盒使用配置的 HTTP(S) 代理和隔离 Docker 网络；默认保持断网。

凭据与诊断数据

• API Key、Token、数据库密码和渠道凭据不写入 URL、Git 或普通日志；可见错误经过脱敏，诊断日志使用受限出口。
• 日志和安全事件使用 fingerprint 记录关联信息，不直接记录用户正文、附件内容或原始身份标识。
• LoopScope 是开发诊断工具，可以在受控界面查看 Trace 正文，但不参与工具执行和业务决策；Collector 不可用时不阻塞 Agent 主链路。

更多实现细节见工具与 Skills 文档、上下文工程文档、工作区 Shell 沙盒设计和LoopScope 文档。

项目结构

gugu/
├─ frontend/      Web 工作空间与 Admin 前端
├─ backend/       API、Agent、Memory、Tools 与数据服务
├─ loopscope/     Agent 可观测系统
├─ docker/        部署与运行环境
└─ docs/          产品、架构、运维与开发文档

后端仍处于持续演进中，具体模块边界以 Backend 文档 和 Agent 架构文档 为准。

开发

环境准备

corepack enable
corepack pnpm install

设计规范

新增或修改前端界面时，应优先复用现有的设计令牌、共享组件和主题变量，不要在页面里重复定义孤立的颜色、字号、间距、圆角或阴影。新增用户可见文案时应接入统一 i18n，不要直接写死在组件中。登录后访问 /design 可以查看当前运行时实际使用的设计令牌、主题和组件状态；具体视觉与交互约束见设计规范。

启动前端

corepack pnpm --filter gugu-web dev

启动后端

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
make dev-web

常用检查

corepack pnpm --dir frontend typecheck
corepack pnpm --dir frontend test:run
corepack pnpm --dir frontend build
cd backend && PYTHONPATH=. .venv/bin/pytest

前端复杂拖拽和画布交互依赖已发布的 gugu-interaction-runtime npm package。Runtime 本身是独立仓库，不在咕咕 workspace 中直接编译。

项目状态与 Roadmap

咕咕当前仍处于快速迭代阶段，下面同时列出已经具备的能力和接下来的重点方向。

状态说明：“稳定”表示已有持续使用和回归验证，“开发中”表示主要流程可用但仍在快速调整，“实验性”表示设计或实现仍可能发生较大变化。