Haocode/docs/agent-handoff/KICKOFF_PROMPT.md

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 必须保持简洁，只保存当前事实，不写成长篇流水账。至少包含：

# 全量修复执行状态

状态：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 连续工作，直到达到上述终止条件。