Haocode/ARCHITECTURE.md

# 项目文件架构

> [!WARNING]
> **历史资料，不是当前事实源。** 本文仅保留旧架构与故障记录。处理修复、跨平台、测试、项目结构或交接任务时，先读 [`docs/agent-handoff/README.md`](docs/agent-handoff/README.md)。

> 仅描述目录与文件的基础组织，不涉及具体实现细节。

```
GeekAgent-Studio/
│
├── main.py                     # 程序入口
├── requirements.txt            # 依赖清单
├── untitled.ui                 # Qt Designer 界面文件
│
├── ui/                         # 表现层（桌面窗口 + 本地 Web 渲染）
│   ├── views/                  # PyQt6 窗口与组件逻辑
│   │   └── system_tools/       # 系统级工具（全局热键、截屏等）
│   ├── web/                    # 本地 HTML/JS/CSS 渲染层
│   │   └── highlight/          # 本地代码高亮库
│   └── assets/                 # 静态资源（样式表、图标）
│       └── icons/
│
├── core/                       # 控制与大脑层（后端核心）
│
├── agents/                     # Agent 逻辑与执行器
│
├── workspace/                  # 智能文件系统与代码编辑
│
├── tools/                      # 动态 Skill / Tool 生态
│   ├── builtin_tools/          # 内置基础工具
│   └── dynamic_skills/         # 动态生成的工具脚本
│
├── data/                       # 本地数据与缓存
│   ├── attachments/            # 聊天附件
│   └── .agent_history/         # 文件修改备份
│
├── svg/                        # 界面图标资源
│
└── tests/                      # 测试用例
```

---

## 流式显示诊断体系（2026-07 新增，重要）

**历史教训**：`dist/GeekAgent-Studio/` 是 PyInstaller 打包产物，`ui/web` 被冻结在
`_internal/ui/web/` 里——**改源码不影响 exe**。修 UI 问题后必须重新打包
（`python -m PyInstaller geekagent.spec --noconfirm`），否则用户跑 exe 永远看不到修复。

**链路诊断日志**（`stream_diag.log`，应用根目录，每次启动清空）：
- Python 侧：`APP_START` / `FRONTEND_VER <前端版本戳>` / `CHUNK`（前 3 条 + 每 50 条
  + 会话不匹配时全记）/ `THINK` / `RESTORE` / `JS_DIAG`（回复完成时抓 JS 事件环）
- JS 侧：`window.__APP_VER` 版本戳 + `__diag` 事件环（createMessage / appendToken
  采样 / tokenDOM 缓冲长度 vs DOM 长度 / NO_WRAPPER 告警 / restore / history / finish）
- 读日志即可回答：token 到了吗？wrapper 在吗？缓冲有内容吗？DOM 写进去了吗？

**助手正文透明气泡**（用户方案）：`.message.assistant .md-segment` 浅灰半透明底 +
圆角边框，流式中/完成后视觉一致；正文段元素在首个 token 时同步创建，气泡即时出现。

---

## Agent 核心（core/agent）— pi 1:1 移植

```
core/agent/
├── types.py        # AgentMessage(kind 标记压缩摘要) / AgentConfig / 事件 / ToolCall / ToolResult
├── context.py      # token 估算（usage 锚定 + CJK 感知）/ 输出钳制 / 压缩触发公式
├── stream_fn.py    # openai_stream：流式 + tools 序列化 + OpenAI⇄pi 消息转换
├── tools.py        # bash(shell=True) / read / write / edit + 文本兜底解析器
├── loop.py         # run_loop：系统提示注入 → 流式 → 工具批执行 → 截断保护
├── agent.py        # Agent：事件订阅/发布（subscriber 异常静默，pi 语义）
├── compaction.py   # pi harness 压缩算法 1:1（切点/断轮/迭代摘要/文件附录）
└── recovery.py     # 429/上下文溢出/截断 重试与恢复（pi 精确语义）
```

- 每次发送 → 新 `AgentWorker`（core/llm_engine.py，QThread 胶水层）；
  多轮工具循环在一次发送内部闭环，UI 线程只收 Qt 信号。
- `stream_fn` 协议：`stream_fn(context, model, signal, max_tokens, tools=None)`；
  `tools` 必须序列化进 OpenAI 请求体（否则模型只能"文字扮演"工具调用）。
- `SYSTEM_PROMPT.md`（项目根）：worker 模式每次请求头部注入，不入历史、不受压缩影响。

### 上下文管理与压缩（2026-07-21 升级为 pi harness 原版算法 1:1）

对照 `packages/agent/src/harness/compaction/compaction.ts` + `utils.ts` 逐函数移植：

- **触发公式**：`shouldCompact: tokens > contextWindow − reserveTokens`，
  `reserveTokens=16384`（`AgentConfig.compaction_reserve`），替换旧 40% 启发式。
- **token 估算**：usage 锚定 1:1——最后一条有效 assistant（非 aborted/error 且
  totalTokens>0）的精确值 + 其后消息逐条估算；无 usage 则全部逐条。
  逐条估算用 CJK 感知版（唯一已声明偏差：pi 是 chars/4）。
- **切分点** `find_cut_point`：从尾部回扫累计 token 至 `keepRecentTokens=20000`，
  取该位置起第一个有效切点（user/assistant；toolResult 不可切）；
  切点非 user → **断轮**：轮起点前的历史与轮前缀**分两次 LLM 摘要**，
  拼接 `{history}\n\n---\n\n**Turn Context (split turn):**\n\n{prefix}`。
- **迭代式更新**：上次压缩摘要（`kind="compaction_summary"` 消息）不重摘，
  作为 `<previous-summary>` 走 `UPDATE_SUMMARIZATION_PROMPT`（pi 四套提示词逐字移植）。
- **文件操作附录**：摘要范围内 read/write/edit 工具的 path 提取，
  摘要尾部追加 `<read-files>/<modified-files>`（1:1 utils.ts）。
- **摘要预算**：`maxTokens = min(0.8×reserve, model.maxTokens)`；轮前缀 `0.5×reserve`。
- **对话序列化**：`[User]:` / `[Assistant thinking]:` / `[Assistant]:` /
  `[Assistant tool calls]:` / `[Tool result]:`（超 2000 字符截断）逐字一致。
- **唯一已声明偏差**：摘要 LLM 调用失败时降级为机械摘录（pi 返回错误），
  桌面应用优先不丢上下文。
- 架构级差异：会话重启后 agent 内存态不持久化（DB 只存时间线），
  压缩摘要随之丢失、上下文从零重建——与 pi 的 compaction 条目落盘不同（见桌面文档）。

## 时间线持久化（2026-07 新增）

agent 模式的完整事件时间线按序落库，切会话/重载后 1:1 还原：

```
messages.timeline  (JSON, 可空)
[
  {"t":"think", "text":"…"},
  {"t":"text",  "text":"…"},
  {"t":"tool",  "id":"call_x", "name":"bash", "args":"{…}",
                 "ok":true, "result":"…"}     # ok:null = 仍在执行
]
```

- **累积**：`MainWindow._active_streams[session]["timeline"]` 从
  reasoning/chunk/tool 三组 Qt 信号按到达顺序累积。
- **入库**：正常结束 / 中止 两条路径都带 `timeline` 写 `db.add_message`。
- **重载**：`load_messages_to_web` 对带 timeline 的 assistant 行调
  `renderTimelineHistory`（静态时间线：思考折叠、chip 定格、文本完整渲染）。
- **切回进行中会话**：`restoreStreamingTimeline` 按流式状态恢复，
  后续 token 无缝续流（续接紧邻的进行中块，否则新开一段）。
- **API 上下文重建**：`build_api_context` 对带 timeline 的行重建完整链
  （assistant+tool_calls → tool 消息），模型跨轮次工具记忆不丢。
- 旧消息（无 timeline 列值）走原有聚合渲染，向后兼容。

## 流式渲染鲁棒性 + agent 运行期 UX（本轮新增）

### 1. 流式内容可见性 —— 不依赖 rAF / 页面定时器

根因：正文/思考内容原来只在 `requestAnimationFrame` 回调里写入 DOM；
rAF 依赖合成器 BeginFrame，在 GPU 上下文丢失（本机 AMD 核显实测会
周期性 context lost）/窗口隐藏/页面被判定后台（rAF 停发 + timer
钳制 1Hz）等环境下，内容永久空白（思考块/工具 chip 是同步插入 DOM
的所以看得见）。

对策（三层，均不依赖页面帧/定时器）：
1. **同步渲染通道** `syncRenderThrottled`：`appendToken`/`appendReasoning`
   在同一 JS 任务内 30ms 节流直接写 DOM（token 由 Python runJavaScript
   送达，必被执行）；
2. **恢复路径同步上屏**：`renderTimelineEntries(liveMode)` 结束即
   `syncRenderThrottled(msgId, 0)` —— 中途切回会话，恢复的正文/思考
   不等任何帧立即显示；
3. **Qt 看门狗**（`MainWindow._render_watchdog`，200ms）：对当前会话
   活跃流 `forceRenderNow(msgId)`（幂等，尾部无变化时近零开销）。

另有：`doStreamingRender` 逐段 try/catch（解析异常 → 全量重解析）；
rAF 通道保留作平滑优化 + 40ms setTimeout 兜底；收尾取消全部定时器。

回归测试：`smoke_live_guard.py` Phase 0（rAF+全部页面定时器 kill →
burst 后 400ms 内容必现）+ Phase A（仅 rAF 卡死 → 40ms 兜底）；
`smoke_midswitch.py`（流式中切走→切回：块顺序/正文/思考/DB 完整 +
切回后立即同步可见）。

### 2. 深度思考：默认收起 + 进行中蓝色动画

- 流式/恢复/历史三条路径的思考块一律 `open=false`；
- 进行中块带 `.streaming-think`：标签蓝色呼吸 + 省略号动画（CSS
  `think-breathe` / `think-dots`）；
- 收尾移除动画类，标签还原「已完成深度思考」。

### 3. bash chip：耗时 / 命中超时徽章

- bash 工具结果自带 `[exit N] (X.Xs)` 与 `命令超时（>Ns）已终止`；
- `_parseToolTiming` 解析后在摘要行插入 `⏱ X.Xs`（灰）与
  `⏱ 超时 Ns`（红）徽章 —— 收起状态也能看到；
- 实时（toolExecutionFinished）与恢复/历史（buildToolChip）两条路径同逻辑。

### 4. 工具结果：展开必显示 + 长结果尾部预览 + 展开按钮

- 修复旧 bug：`toolExecutionFinished` 原来只在 `chip.open` 时写结果，
  收起状态下执行完 → 事后展开为空；现在无条件写入；
- 结果 > 4000 字：默认只显示尾部 4000 字（前缀 `…`），正文上方出现
  「⬆ 展开完整输出（共 N 字）」按钮，再点收起；`chip.__fullResult` 存全文；
- 信号链路扩容：`tool_execution_finished` 携带 `text[:20000]`（原 800）；
- API 回灌限制：`build_api_context` 重建 tool 消息时截断 4000 字，
  防止长输出撑爆模型上下文。

---

## 流式正文不显示：深度调试与根因（2026-07）

### 现象链
旧版（逐 token 全量 innerHTML 同步重绘）正文可见但乱序 → 时间线重构后（缓冲+rAF 增量渲染）正文流式期不显示，结束后/切回后可见。

### 诊断数据（用户环境 stream_diag.log，前端 v2）
- `FRONTEND_VER 20260721-v2` ✓ 最新前端在跑
- CHUNK/THINK 逐 token 到达 UI 线程，会话匹配 ✓
- JS_DIAG 完成时刻环形缓冲 = 思考事件以 ~95/s 流入 → **JS 线程活着，token 在被处理**
- 结论：不是 JS 没跑，是**屏幕没有把 DOM 变化画出来**

### 根因（本机复现）
AMD 核显 GPU 上下文周期性丢失：
- 带 `--enable-gpu-rasterization --ignore-gpu-blocklist`（旧默认）离屏实测：
  连续 `SharedImageStub: context already lost` 错误 → **页面 JS 处理/Qt 定时器全部停摆**
- 加 `--disable-gpu` 后同样代码 100% 正常（真实消息内容回放探针 b/d 双满）
- 用户屏幕上的部分停摆：DOM 已写入，但 GPU 光栅化产物无法合成上屏 → 正文不可见

### 修复
1. **main.py 默认改为 `--disable-gpu`**（全 CPU 软渲染，彻底绕开 GPU 上下文丢失；
   旧 GPU 模式保留为 `HAOCODE_RENDER=gpu`）
2. 保留双保险渲染通道（同步节流渲染 + 200ms Qt 看门狗 forceRenderNow）
3. v3 探针：`probeStream()` 每 2s 写入 `PROBE` 日志（缓冲长度/DOM 长度/offsetHeight/opacity/display），
   `dumpDiag` 改为按类型摘要 —— 若再异常可一次性定位断点

### 最终根因（2026-07-21 v7，推翻上述 GPU 主因结论）
人肉 debug（token 级日志 + 屏幕截图 + 逐层盒模型探针 + 页面内对照/克隆实验）锁定：

**Chromium 布局失效 bug：空 `.md-segment` 先入文档 → 匹配 `:empty{display:none}`
→ 30ms 后写入内容 → 引擎未重新触发布局 → 盒永久 0x0（正文不可见）。**

证据链：
1. token 日志：正文 `段buf` 与 `dom`（textContent）同步增长（71c 全在 DOM），但 `h=0`
2. 像素分析 `diag_shot_*.png`：完成时刻屏幕上也无正文（切会话才可见 = DB 重渲路径）
3. 逐层探针：seg 的祖先链全部存活（reply-content w=119/h=75），唯 seg 子树 w=0/h=0
4. 对照实验：同容器新建的 `.md-segment`（带内容）h=24 正常；原始流式段 h=0
5. 克隆实验：原节点的**完整克隆 h=24**；把原节点**重新 appendChild 一次即恢复 h=24**
   —— 纯布局状态腐坏，与 CSS 规则无关

为什么切会话重渲正常：`renderTimelineHistory` 创建节点时**先填充 innerHTML 再插入**，
从不以空节点进文档，`:empty` 从未匹配。

### v7 修复（真正根因）
1. **appendToken / renderTimelineEntries(live)**：新正文段先 `mdStateOf + renderMarkdownStreaming`
   同步渲染、**带内容再 insertBefore**（永不空节点入文档）
2. `.md-stable/.md-tail`：`display:contents` → `block`（规避 contents 布局风险，加内层边距补偿）
3. 周期性流式截图改为 `HAOCODE_SHOT=1` 可选 —— 实测 `QWidget.grab()` 强制出帧会
   阻塞渲染器主线程 1-2s，会干扰正文 token 处理（诊断干扰项）
4. 保留 `--disable-gpu` 默认（对离屏测试环境仍有必要）与双通道渲染 + 看门狗
5. 新增 `tests/verify_onscreen.py`：**真实窗口真实布局**验证（offscreen 无布局，
   此类 bug 离屏测不出来；本 bug 即由此漏检 3 轮）
6. v6 起 JS 端带渲染器主线程心跳（dt>1.5s 告警）+ finish 后正文段体检日志