sorrow404null
bc0b92bcdc
Add docs/agent-handoff (backlog, execution state, verification, platform plan, per-task evidence), repo AGENTS.md, and architecture notes updated for the dual-renderer design.
363 lines
12 KiB
Markdown
363 lines
12 KiB
Markdown
# 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 连续工作，直到达到上述终止条件。
|