penguin-harness/packages/docs/content/web-app.zh.md

title, description

title	description
Web App 指南	按页面组织的 Web App 使用指南：登录、Chat、Agent 管理、模型、用量与 Trace。

PenguinHarness 自带一个开箱即用的 Web App：多用户登录、流式对话、Agent 配置、模型与用量管理都在浏览器中完成。本文按页面组织，逐一介绍各页面的功能与操作。安装与首次启动见快速开始。

目录结构

packages/web/src
├── api/          # fetch 封装 · 每个 API 一个函数(DTO type-only 来自 @prismshadow/penguin-server/api)· SSE 封装
├── state/        # auth / project / sessions / theme / locale 五个 context
├── lib/omni/     # OmniMessage 流 → 渲染视图模型 reducer;连接先行 + 去重的流控制器
├── components/   # ui 原语(modal / drawer / select …)与应用布局
└── features/     # chat / agents / skills / models / usage / traces / benchmark / admin 各页面

启动与登录

penguin web
# 打开 http://127.0.0.1:7364

初始账号为 admin / penguin-2026。系统不开放自助注册：账号由管理员在用户管理页创建；每个新用户会自动获得一个独立的初始 Project，命名为 <userId>-default_project。仍在使用初始密码时，页面会以横幅提示尽快修改。

登录状态保持 7 天（滑动续期）；管理员重置密码会使该用户的全部登录会话失效。

界面语言（中文 / English / 跟随系统）与主题（浅色 / 深色 / 跟随系统）可随时切换。

Chat 页面（/chat）

新建会话

新会话从草稿开始：先选择 Agent、Workspace（服务器端目录浏览器选取）、审批模式、模型与思考等级，再发送第一条消息。Session 在首次发送时才真正创建，此后该会话的模型与 Workspace 即被锁定。草稿里切换思考等级或模型时，切换后的值即成为新的默认：思考等级立即写回所选 Agent 的 model.thinking_level，所选模型则作为下一个新会话的默认延续。进行中的会话里，思考等级是逐轮参数：输入区拾取器初始显示 Agent 配置的档位并自动跟随（未选择时发送不携带档位，配置修改持续生效），选定后即固定为该会话档位、随每次发送下发（不写回 Agent 配置）；模型仍在会话内锁定，改用 /model 命令切换模型——与 /agent 交接同一方式：选中模型只是在输入框暂存为一枚 chip，发送时才在同一 Agent 下新建一个使用所选模型、沿用当前 Workspace 的会话并跳转，其首条消息携带 [model_switch_from] 源块（源会话 id、Trace 文件路径、原模型），输入框中的文字随之发出（为空时发一句界面语言的自动消息）；新会话中该源块折叠为一条“已切换模型”横幅，可点击回到原会话，模型需要早前历史时按路径自行读取源 Trace 文件。

审批模式共四种：allow-all（全部放行）、deny-all（全部拒绝）、read-only（仅放行只读工具）、always-ask（每次询问），详见工具与审批。

流式渲染

• 模型文本逐 Token 渲染，思考块可折叠；
• 工具卡片可展开查看参数与输出，执行中显示实时计时；
• 子 Agent 在消息流中只留下一条通栏行，样式与其他折叠步骤行一致（头像、名称、短会话号、运行中转圈，子会话内有待审批时带琥珀色圆点）；点击打开右侧智能体面板——上方是该行所属 Task 派生关系的调用图（节点上显示运行时长，点节点切换），下方是所选子会话的实时对话（含子会话自己的用户消息），嵌套工具卡片与审批与主对话完全一致；面板的显示以任务为界：发送消息开启新任务时默认关闭（进入会话时同样默认关闭），仅在手动打开、或（桌面端）当前任务派生子智能体时重新显示（每个任务自动打开一次，任务内手动关闭后保持关闭到下个任务，且不抢占已打开的工作区面板）；从工具条打开面板或切换 Session 时默认展示最新 Task 的调用图，点旧轮次的行则回看那一轮的调用图；智能体面板与工作区面板不会同时显示，打开一个即关闭另一个；上下文压缩以横幅提示；
• 每个 Task 结束后显示统计行：Token 用量、TPS、耗时与费用。

输入与快捷操作

• Enter 发送，Shift+Enter 换行，支持粘贴图片；
• 「+」菜单收纳输入附加项：上传图片、上传文件与目标模式。附件不限类型（一次最多 20 个，单个 ≤ 10MB、合计 ≤ 12MB；超限的文件在读取前即被拒绝，不会先上传再报错），已选文件按选择顺序以可移除的小卡片显示在文本框上方；只带附件、没有正文也可发送。发送时文件写入该 Session 的 scratchpad（随 Session 一并删除），消息里每个文件追加一行 [attached file: <path>]，对话中渲染为一条「附加文件」提示：文件内容不进入对话，模型用普通文件工具按路径读取；
• 输入 / 打开快捷菜单：触发上下文压缩（/compact）、把会话交接给其他 Agent（/agent）、切换模型（/model）——两个切换命令都只在进行中的会话里提供，草稿没有可切换的对话，Agent 与模型本就在草稿页选定——或勾选已安装的 Skill——所选 Skill 会以 [use_skills] 块随消息发送；
• Task 运行期间输入框保持可用，工具条只保留一个操作按钮：输入框为空时是停止，一旦输入内容即变为发送，其行为遵循工具条「更多设置」弹出分组中的运行中发送方式（一个可扩展的设置面板，草稿态同样可设，选择会被记忆）：插话（默认）把文字以 [user_steering] 用户消息随下一轮送达运行中的 Agent；排队 把整条消息暂存在服务端，本轮结束后自动作为普通新消息发出（期间在输入框附近显示「N 条已排队」提示；队列存放在服务端，刷新页面不丢失）；
• /agent 与 /model 都是暂存而非立即生效：选中的 Agent 或模型只在文本区上方留下一枚 chip，此时不发送任何内容，可以继续输入——按 Enter / 点发送才真正交接（为该 Agent 新开一个对话）或换用所选模型继续本对话，输入的文字随之带走；正文为空时自动填入默认消息，点 chip 上的 × 即可取消。两枚 chip 都随草稿缓存，刷新页面或切到别的会话再回来时与文字一同恢复；其中切换模型还需等待会话空闲——新会话要从本会话的 Trace 接续，而运行中的一轮或压缩仍在写入——等待期间输入框上方会给出说明；
• 需要人工审批时，工具调用在消息流中内联显示“允许 / 拒绝”按钮；审批模式在会话中途可随时调整；
• 引擎在重连退避等待（≥2 秒）期间，重试提示行会实时倒计时到下一次尝试，并内联提供立即重试（跳过剩余等待）与放弃（普通中断）两个按钮；
• 模型 API 拒绝该 Session 的凭据（鉴权失败）时，输入框会置灰禁用——但可恢复：Session 锁定的只是模型引用，凭据取自当前 Project 配置。提示条的主按钮跳转到模型配置页；在那里保存新的 API key 后输入框会自动解锁（已打开的标签页经 credentials_updated 事件即时解锁；刷新后也保持解锁，因为凭据更新时间晚于记录的鉴权失败时间）。「重试」按钮可手动清除该状态再试一次（key 仍无效时会重新变灰），一次成功的请求总会清除该状态，「新建会话」仍作为跳到全新草稿的出口。禁用态的输入框保留草稿且可选中——发送失败的长消息仍能复制出来。

文件面板

文件面板可浏览 Workspace 目录树、预览文件（Markdown / HTML 渲染显示）、上传文件（单个 ≤ 14MB）与下载文件。

Agent 管理（/agents）

列表页支持创建与删除 Agent；点击进入 /agents/:agentId 设置页，按标签页组织：

标签页	内容
Overview	基本信息、Agent State 快照的导出 / 导入，以及还原为默认配置（覆盖自定义内容，仅保留名称与描述）
Prompt	AGENTS.md 与 system_prompt
Runtime	max_turns、model.、compaction. 等运行参数
Tools	内置工具表格（含条目级 call_description 开关）与 MCP Server 的 JSON 配置
Vault	环境变量条目，值以掩码显示
Schedule	定时任务（TOML 定义）：创建、编辑、启停、删除

定时任务按固定周期触发（最短 5 分钟），且仅在服务运行期间执行。

Skill 库（/skills）

按分组浏览 Skill 库，可将 Skill 安装到指定 Agent，或一键带入 Chat 草稿快速调用。

模型配置（/models）

按 Provider 分组展示当前 Project 的模型表格。支持添加与编辑模型：以 (provider, model_id) 为唯一标识，凭据以掩码显示，可配置上下文窗口、最大输出长度（按模型的输出上限，覆盖 Agent 的 model.max_tokens——小上下文模型建议调低）、定价与视觉（vision）标记；可设置默认模型与视觉模型（在会话模型不支持图片输入时代为读图），并对任一模型做连通性测试。仅 Project Owner 可编辑，概念说明见模型与 Provider。

用量统计（/usage）

• 筛选条件：Agent、模型、日期范围；
• 概览卡片：今日 / 近 7 天 / 累计用量；
• 图表：各 Agent 占比、各模型成功率、每日 Token 与费用趋势；
• 服务端错误面板：汇总最近的服务端错误记录。

Trace 浏览（/traces）

按 Agent → 日期 → Session → Trace 文件逐级下钻。每回合卡片展示上下文占用环形图与缓存构成，并提供泳道式执行时间线与完整事件列表。Trace 的存储模型见 Session 与 Trace。

Benchmark（/benchmark）

只读展示各 Benchmark 的评分板，可切换指标（得分 / 费用 / 耗时），下钻查看每个 Case 的多次运行结果，并跳转到关联的 Session 与 Trace。配合自我进化工作流使用。

用户管理（/admin/users）

仅管理员可见：列出与创建用户、重置密码、删除用户（内置 admin 不可删除）。

版本与更新

侧边栏用户菜单在「修改密码」下方提供手动「检查更新」按钮，当前运行版本号以浅色显示在该行右侧；其发布日期（由发布流程在构建时打入、直接显示、无需联网）以「最近更新日期 7 月 26 日」样式的悬浮提示展示（开发构建以及打入机制之前的发布版，v0.1.2 及以前，没有日期）。新对话页在品牌下方以版本行显示同样的信息。菜单首次打开后会向 GitHub 查询是否有新版本；点击「检查更新」则立即查询（绕过缓存结果），已是最新时以提示告知。发现新版本时，用户按钮上会出现提示圆点，版本显示处会出现「有新版本可用」上标小徽标（新对话页的徽标可跳转 Release 页面），菜单内提供更新说明链接；管理员还可点击"立即更新"，在服务器上执行 penguin update（数据目录不受影响）。更新完成后需要重启服务才会生效。设置 PENGUIN_UPDATE_CHECK=off 可完全关闭新版本检查——见配置参考。

Project 与成员

侧边栏提供 Project 切换器，并支持创建新 Project。成员分为 Owner 与 Member 两种角色：Owner 负责成员管理，并独占模型、Vault、Schedule 的编辑以及各类删除操作。

生产部署

服务端自身托管构建好的 SPA（同源、SPA fallback），生产环境只需运行 penguin web 或 penguin server 一个进程。npm 安装包已内置前端产物；如需自定义静态目录，可用 PENGUIN_WEB_DIST 覆盖，见配置参考。