Haocode/docs/agent-handoff

haocode 维修交接入口

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

本目录是 2026-09-16 之后的维修与跨平台工作的唯一交接入口。当前交付固化事实、决策、任务和验收方式；业务代码修复已按 REPAIR_BACKLOG.md 状态表推进（任务完成状态以该表和 EXECUTION_STATE.md 为准）。

精确实现仍以源码和可重复测试为准。若本文档与源码冲突，先记录证据，再修正文档；不要用旧文档覆盖已经核实的代码事实。

强制读取顺序

后续 Agent 必须从仓库根目录开始，按以下顺序读取：

1. AGENTS.md
2. docs/agent-handoff/README.md（本文件）
3. 根据任务类型，只读取下表对应的文档

触发条件	接着读取	用途
准备领取或实施修复任务	REPAIR_BACKLOG.md	任务顺序、允许范围、禁止事项、完成条件
涉及 Windows/Linux、渲染器、shell、热键或截图	PLATFORM_PLAN.md	已冻结的跨平台契约
涉及测试、诊断脚本或验收	VERIFICATION.md	分层测试矩阵与证据要求
需要了解目录、命名、模块边界或技术债	CURRENT_STATE.md	已核实的当前状态

不要从 readme.md、Frame.md 或 ARCHITECTURE.md 开始。这三份文件只能作为历史背景；其中的路径、打包说明和完成状态可能已经失效。第三方提供的《haocode 修复需求》也不是事实源，其中只有经源码核验并写入 REPAIR_BACKLOG.md 的内容有效。

永久操作约束

• 将 data/config.json 视为不透明的本机密钥文件。不得打开、读取、搜索、打印、复制、修改或让它进入 Agent 上下文；任何递归内容搜索都必须排除它。
• 测试必须使用临时配置和临时数据库，并在导入 MainWindow 前完成重定向（统一用 tests/_test_env.py 的 isolate()）。自 P0-01 起所有运行时配置读取统一走 core/config_paths（HAOCODE_CONFIG_FILE 优先）；少数 GUI 测试脚本（如 smoke_offscreen.py）自身不设置该环境变量，独立运行时由环境注入临时配置，P2-04 聚合入口将按子进程强制注入。
• 不初始化 Git，不伪造提交历史。任务按可独立提交的粒度编写，等仓库以后具备 Git 历史再逐项提交。
• 不引入 WebKitGTK。Windows 使用 WebView2（首选）或 QtWebEngine（回退）；Linux 只使用 QtWebEngine。
• 不新增 Agent shell 沙箱、审批或路径边界；Chromium 渲染进程的 sandbox 保持默认开启。
• 不拆分或移动现有模块，不借修 bug 增加新产品功能。允许修改确认错误的源码，并新增聚焦测试、平台适配器、文档和配置样例。
• 本阶段以 Windows/Linux 源码运行正确为目标；PyInstaller、安装器、AppData/XDG 目录迁移和发行包是下一阶段。
• 不比较或移植 Claude Code、Codex、Grok Build、DeepSeek Harness。当前 core/agent/ 继续保持 pi 的 Python 移植定位。

文档职责

• CURRENT_STATE.md 只记录已经从仓库核实的事实与结构/命名结论。
• PLATFORM_PLAN.md 是平台行为的唯一决策源。
• REPAIR_BACKLOG.md 是工作拆分和改动边界的唯一决策源。
• VERIFICATION.md 是测试命令、平台矩阵和验收证据的唯一决策源。
• EXECUTION_STATE.md 是无人值守执行与上下文压缩后的唯一恢复入口；任务权威状态仍以 REPAIR_BACKLOG.md 为准，执行证据放 evidence/。

同一规则不要在多份文件中复制扩写。需要变更决策时，先修改其唯一归属文档，再更新这里的路由；不要在实现过程中悄悄改变范围。

领取任务

1. 从 REPAIR_BACKLOG.md 选择一个未完成任务 ID。
2. 只读取该任务列出的源码和它引用的规范文档。
3. 先建立最小复现或失败测试，再修改允许范围内的文件。
4. 运行任务的聚焦测试；阶段结束时再运行 VERIFICATION.md 指定的完整自动化集合。
5. 记录实际命令、结果和平台证据。没有运行的测试必须明确写“未运行”，不能按通过处理。

任务完成的含义是：行为、回归测试、平台适用性和文档中的完成条件全部满足。只提交代码或只写说明都不算完成。