Learning Guide

这份指南回答三个问题：谁适合读、怎么跑、每个阶段怎么确认自己真的学会了。

适合谁

• 你已经能写一个简单 tool-calling agent，但不知道桌面 agent harness 怎么分层。
• 你想理解 session、sidecar、memory、compaction、audit、automation 这些工程机制。
• 你希望像 learn-claude-code 一样，一章一章跑代码，而不是只看架构图。

不需要先会 Electron。这个仓库用 Python 教学实现解释架构边界，Electron 只作为桌面产品分层的概念背景。

30 分钟快速路线

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

python3 examples/full_tour/code.py
python3 s01_agent_loop/code.py --demo
python3 s04_permission_hooks/code.py --demo
python3 s10_workspace_memory/code.py --demo
python3 s14_context_compact/code.py --demo
python3 s24_comprehensive/code.py --demo

这条路线不需要 API key。你会看到完整 harness 的离线链路，以及 agent loop、安全门、记忆、压缩、综合集成这些关键机制。

深度路线

阶段	章节	目标	验收命令
Agent Core	s01-s04	理解模型、工具、权限之间的反馈环。	python3 s04_permission_hooks/code.py --demo
Desktop Runtime	s05-s09	理解 UI、sidecar、session、transcript 的分层。	python3 s09_jsonl_transcript/code.py --demo
Context & Memory	s10-s15	理解记忆选择、输出外部化、压缩和 prompt 组装。	python3 s15_prompt_assembly/code.py --demo
Extensions	s16-s20	理解 skills、connectors、experts 和交付层。	python3 s20_result_presentation/code.py --demo
Production Harness	s21-s24	理解 SQLite、自动化、审计和综合 loop。	python3 s24_comprehensive/code.py --demo

跑完整套：

python3 scripts/verify.py

真实模型路线

推荐先用 DeepSeek，因为它能复用 Anthropic-compatible tool_use/tool_result 形状，章节脚本和 mini harness 都能跑。

cp .env.example .env
# 编辑 .env，填 DEEPSEEK_API_KEY

python3 examples/mini_workbuddy_demo/code.py --mode real --provider deepseek
python3 examples/full_tour/code.py --provider deepseek
python3 scripts/run_real_smoke.py --provider deepseek --targets mini full s01 s24

每个章节都支持统一模型评测入口，评测会写出 JSONL trace：

python3 s03_deferred_loading/code.py --eval --provider deepseek

全章节真实模型 smoke：

python3 scripts/run_real_smoke.py --provider deepseek --targets all-lessons

OpenAI 路线分两种：

• --provider openai：OpenAI Responses API，覆盖 mini harness / full tour / 24 章 eval。
• --provider openai-chat：OpenAI-compatible Chat Completions 网关，覆盖 mini harness / full tour / 24 章 eval。

章节交互 CLI 多数保留 Anthropic-compatible message shape；统一 --eval 入口走 mini_workbuddy.providers，所以 GPT 网关也能批量评测章节。

卡住时看哪里

问题	看这里
没有 API key	先跑 --demo 或 --provider offline。
DeepSeek 跑不起来	检查 .env 里的 DEEPSEEK_API_KEY 和 DEEPSEEK_MODEL。
OpenAI provider 报错	确认 pip install -r requirements.txt 已安装 openai。
章节跑到真实家目录	教学章节用 WORKBUDDY_HOME=/tmp/learn-workbuddy；统一 eval 用 MINI_WORKBUDDY_HOME=/tmp/mini-workbuddy。
安全边界困惑	先读 docs/security-boundaries.md。
clean-room 边界困惑	先读 docs/legal/clean-room.md 和 NOTICE.md。

最后验收

学完后，你应该能画出并解释这条链路：

UI shell -> sidecar/session runtime -> agent loop -> tool registry
         -> permission/audit -> transcript/memory/artifacts -> prompt assembly

你也应该能说清楚三大矛盾：

• 上下文有限 vs 信息无限
• 自主执行 vs 安全可控
• 模型成本 vs 任务复杂度

这就是 WorkBuddy-style desktop agent harness 的核心。