Haocode/AGENTS.md

仓库协作规则

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_* 默认表示诊断或人工脚本，除非文件自身另有说明。

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。