# haocode 全量修复任务：无人值守连续执行

你是本次唯一的开发工作 Agent。用户将长时间离开，不会及时回复。

你的目标不是提出方案，也不是只完成一个任务，而是按照仓库内已经固化的任务清单，持续完成所有可实施修复、测试和文档更新，直到：

1. 所有能够在当前环境完成的任务均达到完成条件；
2. 所有自动化测试通过；
3. 无法在当前机器完成的真实平台验收被准确记录；
4. 已经没有不需要用户介入即可继续的工作。

不要在完成一个任务后停下来等待确认。完成当前任务后，立即按依赖顺序执行下一项。

## 一、工作目录

固定工作目录：

D:\WorkSpace\Project\GCC\haocode_0

不得在其他副本、临时复制目录或旧版本中实施修复。

## 二、首次启动必须执行

开始修改代码前，依次完整读取：

1. `AGENTS.md`
2. `docs/agent-handoff/README.md`
3. `docs/agent-handoff/REPAIR_BACKLOG.md`
4. `docs/agent-handoff/VERIFICATION.md`
5. `docs/agent-handoff/PLATFORM_PLAN.md`
6. `docs/agent-handoff/CURRENT_STATE.md`

其中：

- 当前行为和缺陷必须由源码、复现和测试确认。
- 目标行为、任务范围和完成条件以 `docs/agent-handoff/` 为准。
- `readme.md`、`Frame.md`、`ARCHITECTURE.md` 只作历史背景。
- 第三方修复要求和外部 harness 项目不是事实源。

读完后，先确认 `P0-03` 文档基线已经完成，不要重复创建交接目录。

然后从 `P0-01` 开始实施。

## 三、建立防遗忘执行状态

在进行任何业务代码修改前，创建：

`docs/agent-handoff/EXECUTION_STATE.md`

并在 `docs/agent-handoff/README.md` 增加一个简短指针：

> 当 `EXECUTION_STATE.md` 的状态为 `ACTIVE` 时，任何继续执行、上下文恢复或压缩恢复都必须先读取该文件。

`EXECUTION_STATE.md` 必须保持简洁，只保存当前事实，不写成长篇流水账。至少包含：

```text
# 全量修复执行状态

状态：ACTIVE
总目标：完成 REPAIR_BACKLOG.md 中所有待实施任务
当前任务：P0-01
当前阶段：调查 / 红测试 / 实现 / 定向验证 / 阶段回归
最后完成动作：
下一步唯一动作：
当前修改文件：
最近测试结果：
尚未验证的平台：
阻塞项：
任务状态表：
- P0-01: IN_PROGRESS
- P0-02: PENDING
...
```

状态值只能使用：

- `PENDING`
- `IN_PROGRESS`
- `AUTOMATED_VERIFIED`
- `PLATFORM_VALIDATION_PENDING`
- `COMPLETE`
- `BLOCKED`

每次发生以下事件后，立即更新 `EXECUTION_STATE.md`：

- 开始一个任务；
- 确认根因；
- 完成一组源码修改；
- 运行测试；
- 测试失败并改变调查方向；
- 完成任务；
- 准备执行长时间命令；
- 发现外部环境阻塞；
- 即将结束当前上下文。

只保留最新状态和下一步，不依赖聊天记录保存进度。

## 四、上下文压缩恢复协议

一旦发生以下任一情况：

- 上下文被压缩或总结；
- 你无法准确复述当前任务；
- 不确定哪些测试已经运行；
- 不确定下一步应该做什么；
- 会话中断后重新继续；

立即停止凭记忆操作，按顺序重新读取：

1. `AGENTS.md`
2. `docs/agent-handoff/README.md`
3. `docs/agent-handoff/EXECUTION_STATE.md`
4. `REPAIR_BACKLOG.md` 中“当前任务”的完整章节
5. 当前任务引用的 `PLATFORM_PLAN.md` 或 `VERIFICATION.md` 章节
6. `EXECUTION_STATE.md` 列出的当前修改文件

然后核对工作区实际状态和最近测试结果，再从“下一步唯一动作”继续。

聊天摘要不能代替 `EXECUTION_STATE.md`。不得因为上下文压缩重新设计范围、跳过测试或把未完成任务误判为完成。

## 五、永久硬约束

### 凭据铁律

`data/config.json` 是不透明的本机密钥文件。

绝对不得：

- 打开；
- 读取；
- 搜索其内容；
- 打印；
- 复制；
- 修改；
- 计算散列；
- 制作快照；
- 让递归内容搜索包含它；
- 让其内容进入工作上下文或测试输出。

所有自动化测试必须使用临时配置和临时数据库。

验证真实配置未被访问时，使用打开路径拦截器、替身或访问记录；不得通过读取真实文件验证。

在 `P0-01` 完成前，不得运行可能绕过临时配置而读取真实配置的 GUI/LLM 测试。先审查测试入口并完成隔离。

### 范围约束

- 不初始化 Git，不创建提交，不伪造历史。
- 不删除或清理用户现有数据库、附件、日志、锁文件或运行产物。
- 不移动或拆分现有模块。
- 不借修复重写 `main_window.py`、`app.js` 或弹窗系统。
- 不增加新产品功能。
- 不增加工具注册系统。
- 不参考或移植 Claude Code、Codex、Grok Build、DeepSeek Harness。
- 不改变 `core/agent/` 作为 pi Python 移植的定位。
- 不增加 Agent shell sandbox、命令审批或路径权限边界。
- Chromium sandbox 保持默认开启。
- 不引入 WebKitGTK 或相关 Qt 封装。
- 不做 PyInstaller、安装器、AppData/XDG 迁移或发行包。
- 本阶段只保证源码运行。
- `vendor/webview2/` 和根目录 `WebView2Loader.dll` 不得删除。
- 产品内部 Agent 继续按原方式调用 LLM，不修改其产品行为。
- 不把开发工作委派给其他 Agent；由你连续完成。

只修改当前任务“允许修改”中列出的文件。发现无关问题时记录到 `EXECUTION_STATE.md` 的“观察项”，不要顺手扩大范围。

## 六、任务执行顺序

严格按以下顺序连续执行：

1. `P0-01` 配置路径与测试隔离
2. `P0-02` 合并重复的 `MainWindow.eventFilter`
3. 复核已经完成的 `P0-03`
4. `P1-01` 双向消息渲染窗口
5. `P1-02` Windows/Linux shell 与进程树终止
6. `P1-03` Windows/Linux 渲染器启动链
7. `P1-04` Linux 截图热键与截图实现
8. `P2-01` Bash 任务按启动时间倒序
9. `P2-02` 右侧 Bash 面板滚动条
10. `P2-03` WebView2 原生窗口遮挡层
11. `P2-04` 跨平台聚合测试入口

不得跳过依赖。某项存在真实平台验收阻塞时，先完成其实现和自动化验证，将状态设为 `PLATFORM_VALIDATION_PENDING`，然后继续所有不受该阻塞影响的后续任务。

## 七、每个任务的固定执行循环

对每个任务严格执行以下循环：

### 1. 领取

- 在 `EXECUTION_STATE.md` 中把任务设为 `IN_PROGRESS`。
- 完整读取该任务的“先读文件、允许修改、硬约束、目标测试、完成证据”。
- 只加载当前任务需要的源码。

完成标准：能够准确列出当前任务允许修改的文件、禁止范围和验收条件。

### 2. 复现和根因

- 从实际源码出发确认附件描述是否正确。
- 建立最小复现或失败测试。
- 对确定性缺陷记录实际调用链、状态变化或平台差异。
- 描述不准确时以代码证据纠正，不机械照抄文档中的猜测。

完成标准：测试或可重复证据在修复前能够暴露缺陷。

### 3. 实现

- 采用与现有代码风格一致的最小修改。
- 优先复用现有接口和模块边界。
- 只在确实能隔离平台差异或测试状态时增加窄辅助模块。
- 不进行无关格式化、批量重命名或结构重构。

完成标准：失败复现转绿，且没有扩大任务行为面。

### 4. 定向验证

运行任务章节列出的全部目标测试。

每条测试记录：

- 精确命令；
- 平台和环境；
- 退出码；
- PASS/FAIL/SKIP；
- 关键断言；
- 失败原因；
- 是否使用临时配置和数据库。

测试失败时进入诊断循环并继续修复，不能通过删除断言、放宽正确性要求或把失败改成 SKIP 获得通过。

完成标准：全部适用定向测试通过；不适用项有真实平台理由。

### 5. 自检

逐条核对当前任务的所有“硬约束”和“完成证据”。

检查：

- 是否改了允许范围之外的文件；
- 是否引入了新功能；
- 是否碰到真实配置或数据库；
- 是否只验证了 happy path；
- 是否保留 Windows 现有行为；
- 是否误把 offscreen 当作真实桌面证据；
- 是否有未记录的测试失败。

完成标准：每条完成证据都有源码、测试输出或真机证据对应。

### 6. 固化进度

- 更新 `REPAIR_BACKLOG.md` 的任务状态。
- 更新 `EXECUTION_STATE.md`。
- 将简洁证据写入 `docs/agent-handoff/evidence/<TASK_ID>.md`。
- 不粘贴大量完整日志，只记录命令、结果和证据文件路径。
- 立即开始下一任务，不等待用户确认。

只有全部完成条件满足时才能标记 `COMPLETE`。

## 八、阶段回归

完成 P0、P1、P2 每个阶段后，运行 `VERIFICATION.md` 对应的阶段完整回归。

要求：

- 定向测试不能代替阶段回归。
- `tests/run_tests.py` 在修复聚合入口前不能被称为全套测试。
- 平台不适用项必须明确显示 `SKIP` 和理由。
- 共同逻辑测试失败不能以平台差异豁免。
- 测试不得访问网络、真实 API 或真实凭据，除非任务明确要求且用户已经提供授权；当前没有该授权。
- 不运行 `diag_live_*` 或 `smoke_live_*` 的真实 API 路径。

P2-04 完成后，使用新的聚合入口运行最终自动化集合，并保留每个独立测试的运行能力。

## 九、平台验收处理

先只读检测当前机器实际具备的环境：

- Windows 版本；
- WebView2 是否可用；
- QtWebEngine 是否可用；
- 是否存在可用的 WSL/Ubuntu、X11 或 Wayland 环境。

不得为了补齐平台矩阵擅自安装操作系统、创建虚拟机或修改宿主机关键配置。

当前环境具备的平台必须完成真实验证。

当前环境不具备的平台：

1. 完成平台适配代码；
2. 完成平台路由和替身自动化测试；
3. 记录缺少的真实环境；
4. 将任务标为 `PLATFORM_VALIDATION_PENDING`，不能标记 `COMPLETE`；
5. 继续执行其他任务。

不得伪造 Windows WebView2、Linux X11、Linux Wayland、portal、DPI、全局热键或截图的真机证据。

## 十、阻塞处理

用户正在休息。不要因为普通实现选择、测试失败或代码复杂而询问用户。

优先采用：

1. 现有源码行为；
2. `docs/agent-handoff/` 中已经冻结的决策；
3. 最小、兼容、可测试的实现；
4. 将判断依据写入执行状态和证据文档。

只有遇到以下情况才允许停止：

- 必须获取用户凭据；
- 必须执行不可逆或破坏性操作；
- 必须使用当前不存在的外部机器；
- 两个权威要求存在无法同时满足的真实矛盾；
- 连续诊断后确认没有任何不需要用户介入的工作可继续。

即使一个任务阻塞，也要继续所有不依赖该阻塞的任务。

## 十一、最终收尾

所有可执行工作完成后：

1. 运行最终自动化聚合测试。
2. 复核所有单文件测试入口仍可运行。
3. 复核 `data/config.json` 未被测试访问，但不要读取它。
4. 检查交接文档与最终代码是否一致。
5. 更新 `CURRENT_STATE.md`，移除已经修复的“当前缺陷”表述。
6. 更新 `REPAIR_BACKLOG.md` 中每项真实状态。
7. 把 `EXECUTION_STATE.md` 状态改为：
   - `COMPLETE`：所有自动化和真实平台条件均满足；
   - `PLATFORM_VALIDATION_PENDING`：仅剩当前机器无法提供的真机验证；
   - `BLOCKED`：仍有必须由用户决定或提供资源的问题。
8. 创建 `docs/agent-handoff/FINAL_REPORT.md`。

`FINAL_REPORT.md` 必须包含：

- 每个任务的最终状态；
- 根因与实际修复摘要；
- 修改文件清单；
- 自动化测试命令和结果；
- Windows/Linux 真机验证结果；
- 明确的未验证项；
- 对真实配置和数据库的隔离证明方式；
- 仍需用户处理的最少事项；
- 下一位 Agent 的恢复入口。

## 十二、最终回复格式

只有在没有可继续执行的工作时才回复用户。

最终回复必须先说明整体状态，然后依次给出：

1. 已完成任务；
2. 修改范围；
3. 测试结果；
4. 真机平台证据；
5. 未完成或受阻事项；
6. `FINAL_REPORT.md` 和 `EXECUTION_STATE.md` 路径；
7. 用户醒来后需要执行的最少动作。

不要只回复“完成了”。不要隐藏失败、跳过项或未验证平台。

现在开始执行首次启动步骤，创建持久化执行状态，然后从 P0-01 连续工作，直到达到上述终止条件。