# agent-panel

**Repository Path**: aaabackup/agent-panel

## Basic Information

- **Project Name**: agent-panel
- **Description**: Agent 状态面板：监控 DSH / Codex / WorkBuddy 三 AI 健康状态的本地面板工具（pywebview 无边框置顶窗口）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent 状态面板 (agent-panel)

> v1.4.6（2026-08-14）· SSE 增量推送 + UI 渲染优化 · 变更见 [CHANGELOG.md](CHANGELOG.md)

独立于任何 agent/harness 的本地状态面板：桌面置顶小窗口（胶囊 ⇄ 可展开面板），
一眼看清 **DSH / Codex / WorkBuddy** 的健康状态，并在"需要人工干预"时提醒。

## 运行

**方式一（推荐，免 Python 环境）— 打包版 exe**：

```bash
python tools/build_exe.py        # 打包 → dist/AgentPanel/AgentPanel.exe
dist/AgentPanel/AgentPanel.exe            # 双击启动（置顶窗口 + 托盘）
dist/AgentPanel/AgentPanel.exe --tray     # 启动即隐藏，只留托盘（开机自启模式）
```

**方式二（源码）**：

```bash
cd D:\DeepSeekHarness\开发\agent-panel
python panel.py            # 启动置顶窗口 + 托盘
python panel.py --tray     # 启动后隐藏窗口，只留托盘（开机自启默认此模式）
python panel.py --headless # 只跑采集与本地服务（调试/无头）
```

- 本地服务：`http://127.0.0.1:17890/`（也可用浏览器打开同一地址）
- 源码依赖：`pip install -r requirements.txt`（pywebview、zstandard、pystray、pillow）
- 打包依赖：`pip install pyinstaller`（打包脚本已处理 pythonnet/平台模块/UI 资源）

## 托盘与自启

- **系统托盘**：常驻图标（随最差状态变色：绿/橙/红/黄/灰）。左键菜单：**显示/隐藏窗口**、**开机自启**（勾选开关）、**退出**。面板右上角 `✕` 在有托盘时变为"隐藏到托盘"。
- **任务栏隐藏**：面板窗口应用了 `WS_EX_TOOLWINDOW`，不占用任务栏按钮（Alt-Tab 也不出现），托盘是唯一任务栏存在。
- **开机自启**：托盘菜单勾选"开机自启"，或手动运行 `python panel.py --tray`（写入注册表 Run 键，用 pythonw 无控制台启动、隐藏窗口只留托盘）。

## 配置（config.json，与面板同目录，改后重启生效）

- `stuck_after`（默认 600s，卡死判定阈值）、`active_window`（300s，工具级"在忙"窗口）、`old_after`（5400s，UI 旧任务折叠阈值）
- `panel_size` / `dock_size_v` / `dock_size_h` / `dock_pos_v` / `dock_pos_h`：面板与停靠条尺寸、位置（由界面操作自动写入，重启保留）

## 用法

- **胶囊**：常驻置顶小条，每工具一个状态点（绿=运行 / 橙=等人 / 红=出错 / 黄=疑似卡住 / 灰=闲置），右上角 `⚠n` 表示待处理提醒数。点击展开。
- **面板**：顶部可拖动；**右下角手柄可手动调整大小**（尺寸会被记住）；"⚠ 需要你处理"区列出待处理事件（可点"已处理"）；下方按工具分**三列**（DSH / Codex / WorkBuddy）展示任务卡片。WorkBuddy 列按**项目分组**：组头显示项目名与状态灯，组内为会话卡片（每个活跃会话一张卡，对齐 DSH/Codex 的会话粒度）。
- **靠边竖条（红绿灯式）**：两种方式进入——
  - **拖拽吸附**：把胶囊/面板拖到屏幕边缘松手，自动吸附成停靠条（窗口覆盖或贴近边缘 ≤24px 即吸附，拖过头同样生效，四边均可）
  - **手动菜单**：面板头部 `▍` 按钮 → 方向菜单（上/下/左/右）点选
  - 停靠后：
  - **按住停靠条本体拖动** → 沿边缘滑动调整位置（竖向只动上下、横向只动左右，全程保持贴边，位置被记忆）
  - **按住底部/右侧的小手柄拖动** → 调节停靠条尺寸（竖向调高、横向调长）
  - **轻点** → 展开回完整面板
- **旧任务收纳**：90 分钟内有活动或状态为运行/等人/出错/卡住的卡片常显；更早的归入列内 `▾ 旧任务 N` 折叠区。卡片 `✕` 可手动隐藏（持久化，列头 `▾ 已隐藏 N` 可恢复）。
- **提醒**：出现"需要人工/疑似卡住/出错"事件时窗口闪动 + 弹出通知条，自动展开面板。
- 拖动窗口：按住胶囊任意处 / 面板标题栏拖动。

## 数据源

| 工具 | 数据源 | 说明 |
|---|---|---|
| DSH | `~/.dsh/sessions/**` + `AppData/Roaming/DSH Desktop/dsh-home/sessions/**` | 多帧 zstd 增量 tail；兼容 CLI/Desktop 双数据源；每会话一卡 |
| Codex | `~/.codex/state_5.sqlite` (threads 表) | 只读查询；标题/token/approval_mode/has_user_event；每线程一卡 |
| WorkBuddy | `%LOCALAPPDATA%\WorkBuddy\logs\main.log` + `~/.workbuddy\logs\**\*.log` + `~/.workbuddy\sessions\*.json` 会话心跳 | 项目级（agent-*，日志活跃）+ 会话级（sess-*，心跳 90s 内），UI 按项目分组展示 |

## 判定规则（阈值在 config.json，改后重启生效）

- `stuck_after`：默认 600s（DSH 因文件刷新滞后放宽到 1800s）
- `active_window`：工具整体 300s 内有活动才算"在忙"；整体都静默 → 一律 idle（不误报批量暂停）
- `waiting_human`：Codex `has_user_event`；WorkBuddy 沙箱弹窗 pending；DSH 审批策略=ask 且停在工具调用
- 事件自动去重（ref 唯一），条件解除自动标记已解决，也可手动点"已处理"

## 安全

- 服务仅绑定 `127.0.0.1`；界面只展示标题/目录/摘要，不展示原始日志正文
- ⚠ WorkBuddy 的 `workbench_data.json` 明文存有 API key、日志含 Bearer token——面板详情已做字段白名单，未来加"查看原文"时必须强制脱敏

## 里程碑状态

- [x] M0 spike 验证（spike/ 目录保留参考）
- [x] M1 三 adapter（DSH/Codex/WorkBuddy）+ 增量 tail + SQLite 历史
- [x] M2 本地服务 + SSE + 三列布局 UI
- [x] M3 waiting_human / stuck / error 判定 + 提醒
- [x] M3.5 增强：手动调节面板大小、多方向停靠（上/下/左/右）、停靠条沿边滑动 + 尺寸调节 + 位置记忆、旧任务折叠 + 手动隐藏（持久化）
- [x] M4a 系统托盘（状态色图标 + 显示/隐藏/退出）+ 开机自启（注册表 + --tray）
- [x] M4b 配置持久化（config.json：阈值 + 尺寸/位置）
- [x] M4c DSH 审批弹窗模拟实测（ask 策略 + 待审批 tool/call → waiting_human + 事件，全链路验证）
- [x] M4d 美化：深色主题打磨（配色/字体/SVG 图标/卡片悬浮/胶囊药丸/列强调色/滚动条/动效）
- [x] M4e WorkBuddy 会话级视图（项目组头 + 会话卡片，与 DSH/Codex 粒度对齐；v1.1.0）
- [x] M4f exe 打包分发（PyInstaller onedir + 自启适配 frozen；v1.2.0）
- [x] M4g 拖拽贴边吸附 + 胶囊拖动修复（v1.3.0 / v1.3.1）
- [x] M4h 视觉体系重构：克制深色配色 + 层次阴影 + 字体体系 + 状态灯动效 + 切换过渡（v1.4.0）
- [ ] 后续：多机扩展、托盘自定义图标

## 已知限制

- DSH 会话文件是周期性 flush，实时性受 flush 频率限制（判定已放宽到 30 分钟）
- WorkBuddy 日志噪音大，过滤规则需随版本维护
- Codex 无进程常驻时按线程活跃度判断（进程名不扫描）
- 单实例互斥：双开时第二个实例直接退出（CreateMutex），避免并发写库
- 打包版 exe 体积约 68MB（pythonnet + WebView2 运行时依赖），首次启动略慢
- 贴边吸附基于主屏工作区检测，多显示器下仅主屏边缘可吸附