docs: add agent handoff docs, verification guide, and repair evidence
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.
This commit is contained in:
@@ -0,0 +1,66 @@
|
||||
# 仓库协作规则
|
||||
|
||||
haocode 是面向 Windows 和 Linux 的 PyQt6 桌面 AI Agent 客户端。Windows 首选 WebView2，失败时回退 QtWebEngine；Linux 只使用 QtWebEngine。`core/agent/` 保持无 GUI，并继续与 pi 对齐。
|
||||
|
||||
## 权威交接入口
|
||||
|
||||
处理修复、跨平台、测试、项目结构或交接任务前，必须先读 `docs/agent-handoff/README.md`，再按其中的触发条件读取对应文档。`readme.md`、`Frame.md` 和 `ARCHITECTURE.md` 只作历史背景，不能未经核验就当作事实源。
|
||||
|
||||
`data/config.json` 是不透明的本机密钥文件。Agent 不得打开、读取、搜索、打印、复制、编辑它，也不得让宽范围内容搜索包含它。测试必须使用临时配置。
|
||||
|
||||
## 项目结构
|
||||
|
||||
- `main.py`：入口、UTF-8 标准输出保护、Chromium 参数和 `MainWindow` 创建。
|
||||
- `core/`：无 GUI 后端，包括 SQLite 会话树、Qt 工作线程、WebView2 后端和日志。
|
||||
- `core/agent/`：与 pi 对齐的循环、流式处理、重试/压缩恢复，以及 `read`/`bash`/`write`/`edit` 工具；可直接进行纯 Python 测试。
|
||||
- `ui/views/`：PyQt6 窗口与桥接。`main_window.py`（约 6000 行）是当前中心，还包括 `bash_panel.py`、`chat_bridge.py`、`wv2_view.py`、`custom_web_page.py`、`debug_window.py` 和 `system_tools/`。
|
||||
- `ui/web/`：离线网页层，包括 `index.html`、`app.js`、`style.css` 及 vendored marked/DOMPurify/KaTeX/highlight.js。
|
||||
- `data/`：源码运行时数据，包括不透明的 `config.json`、自动创建的 `chat_history.db` 和 `attachments/`。
|
||||
- `tools/builtin_tools/pdf_reader.py`、`svg/`（图标）、`SYSTEM_PROMPT.md`（每次请求重新读取，修改后无需重启）。
|
||||
- `vendor/webview2/` 和根目录 `WebView2Loader.dll`：Windows 运行依赖，**不得删除**。
|
||||
- `tests/`：测试、smoke、诊断和人工验证脚本。
|
||||
|
||||
## 常用命令
|
||||
|
||||
- `pip install -r requirements.txt`：安装当前依赖；Linux 依赖规范化见交接任务清单。
|
||||
- `python main.py`：从源码运行。Windows 可从 WebView2 回退 QtWebEngine；Linux 使用 QtWebEngine。
|
||||
- `python tests/run_tests.py`：只运行当前 agent-core 聚合，不会发现整个测试目录。
|
||||
- `node tests/test_math_extract.js`：运行前端公式提取测试。
|
||||
- `python tests/check_db_migration.py <db>`：只读检查数据库迁移完整性。
|
||||
|
||||
## 编码规范
|
||||
|
||||
- 以 Python 3.10 语法为基线，使用 4 空格缩进、`snake_case` 函数/文件名和 `PascalCase` 类名；目标运行矩阵为 Python 3.10–3.12。仓库未配置 formatter/linter，修改时匹配周边风格。
|
||||
- 注释和文档使用中文；路径、命令和 API 标识符保持原文。
|
||||
- `requirements.txt` 只列源码确实导入的包；依赖变更必须有意为之。
|
||||
- `core/agent/` 必须保持无 GUI，确保可离屏测试。
|
||||
|
||||
## 测试规则
|
||||
|
||||
仓库不使用 pytest；测试是可直接运行的 Python/Node 脚本。`tests/run_tests.py` 当前只加载 agent-core 套件。`test_*.py` 表示聚焦自动化测试，`smoke_*.py` 表示离屏集成测试，`diag_*`/`verify_*`/`tune_*` 默认表示诊断或人工脚本，除非文件自身另有说明。
|
||||
|
||||
```bat
|
||||
set PYTHONIOENCODING=utf-8
|
||||
set QT_QPA_PLATFORM=offscreen :: only for smoke_* GUI tests
|
||||
python tests/test_tool_params.py
|
||||
```
|
||||
|
||||
跨平台聚合入口（不改变任何独立命令）：`python tests/run_all.py --group logic|offscreen|all`。每个条目独立子进程 + 临时目录 + 显式超时；依赖/平台不适用项打印明确 SKIP 理由；任一失败则退出码非零。默认不跑 `diag_*`/`verify_*`/`tune_*`/真实 API/真实桌面脚本。
|
||||
|
||||
导入 `MainWindow` 前，必须把 `core.db_manager._DEFAULT_DB` 指向临时数据库，并把 `HAOCODE_CONFIG_FILE` 指向临时配置。当前仍有代码绕过该变量；对应任务完成前，测试还必须 patch 相关模块缓存的路径，并证明真实运行时文件未被访问或修改。
|
||||
|
||||
## 调试铁律
|
||||
|
||||
- **所有调试命令、测试与诊断脚本执行都必须设置显式的最长耗时预算（timeout）**。
|
||||
- 若中途因超时跳出，先定位卡点，再允许延长预算重跑；**严禁不设超时让它无限卡死**。
|
||||
|
||||
## 变更粒度
|
||||
|
||||
当前快照没有 Git 历史。不得初始化 Git 或伪造提交；每批修改仍须保持可独立提交。未来提交信息使用简短祈使句并注明区域，例如 `core/agent: fix compaction cut-point`。
|
||||
|
||||
## Agent 注意事项
|
||||
|
||||
- 运行时可能在根目录写出 `compaction_diag.log`、`stream_diag.log`、`diag_shot_*.png` 等诊断产物。除非当前任务明确负责清理，否则不得删除。
|
||||
- shell 行为尚未规范化。目标契约是 Windows `cmd.exe`、Linux `/bin/bash -lc`；修改前先读 `docs/agent-handoff/PLATFORM_PLAN.md`。
|
||||
- 本阶段源码运行继续把数据放在项目 `data/` 下；打包路径和 AppData/XDG 迁移延后。
|
||||
- 不得删除 `vendor/webview2/` 或根目录 `WebView2Loader.dll`。
|
||||
Reference in New Issue
Block a user