# 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. 记录实际命令、结果和平台证据。没有运行的测试必须明确写“未运行”，不能按通过处理。

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