🔥 从0手搓桌面AI助手 · 24节课复刻WorkBuddy架构
一份开源教学蓝图 — 不是产品源码，是可以跑的 Agent 工程课。
模型是大脑，Harness 是操作系统。
⭐ 如果这个项目对你有帮助，请给个 Star 支持我们继续出课！
🤔 你是不是也被这些卡住了
你写过 CLI agent，能跑通 while True + tool calling，但一到桌面端就卡住了——工程复杂度翻 10 倍：
- 😫 会话常驻、恢复、重连 —— 不是"跑完就关"，是长期活着的进程
- 😫 工具太多时上下文窗口秒炸 —— 模型还没干活就 OOM 了
- 😫 工具输出几 MB —— 塞不进 context，模型直接摆烂
- 😫 长期记忆放哪里、什么时候注入 —— 隐私和成本两头失控
- 😫 Agent 能执行命令 —— 权限怎么设计才不变成后门
- 😫 前端、sidecar、runtime、模型、工具 —— 六层架构的每一层怎么解耦
这个仓库把这些问题拆成 24 课。每一课只新增一个机制，每一课都有一份 code.py 和一张图。
🗺️ 为什么选这个
| 维度 | learn-workbuddy | learn-claude-code | 直接看 WorkBuddy |
|---|---|---|---|
| 定位 | 桌面 Agent 工程系统 | CLI Agent 起点 | 产品使用 |
| 覆盖深度 | sidecar/记忆/审计/自动化 | 单进程/终端/MCP | 黑盒体验 |
| 代码可见 | 24章原创Python教学代码 | 有 | 闭源 |
| 多Provider | DeepSeek/OpenAI/Anthropic | Anthropic | 绑定 |
| 离线可跑 | ✅ 无key跑全部demo | 部分 | ❌ |
| 适合谁 | 想透彻理解桌面Agent架构 | 入门Agent编程 | 日常使用 |
两个项目合在一起，就是从 CLI agent 到 desktop agent 的完整工程谱系。
🧠 30 秒看懂
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 examples/full_tour/code.py
这条命令会离线跑完整 harness tour：provider adapter、session、记忆、工具、权限、外部化、JSONL、HTTP、审计和 artifacts 全部走一遍。想按课程学，走 Learning Guide；想先看图，走 Visual Tour。
🏗️ Harness 总图
flowchart TB
UI["Desktop UI<br/>renderer / chat / tasks"]
Bridge["Preload + IPC<br/>narrow bridge"]
Main["Main Process<br/>window / auth / config"]
AppServer["Local App Server<br/>routing / connector proxy"]
Sidecar["Sidecar Manager<br/>spawn / reconnect / lifecycle"]
Runtime["Session Runtime<br/>HTTP / ACP-like protocol"]
Agent["Agent Loop<br/>model -> tools -> result"]
Tools["Tool Registry<br/>built-in / skills / MCP"]
Memory["Memory System<br/>workspace / user / remote profile"]
Store["Persistence<br/>SQLite / JSONL / artifacts / logs"]
Guard["Safety<br/>permissions / hooks / sandbox / audit"]
UI --> Bridge --> Main --> AppServer --> Sidecar --> Runtime --> Agent
Agent --> Tools
Agent --> Memory
Agent --> Store
Agent --> Guard
Tools --> Guard
Memory --> Store
一句话版本：
桌面 Agent = 用户界面外壳
+ Sidecar / 会话运行时
+ Agent 循环
+ 工具注册表
+ 上下文与记忆管理
+ 持久化存储
+ 权限与审计
模型只是"大脑"。Harness 是让大脑能够长期工作、使用工具、保持上下文、交付文件、接受治理的操作系统。
仓库里还放了一个标准库实现的最小 harness —— Mini WorkBuddy，便于你理解完整请求链路。
📐 六层架构
Layer 1: 用户界面 目标: 功能丰富但不压垮用户
Layer 2: Agent 推理 目标: 自主决策但可被编排
Layer 3: 工具执行 目标: 能力强大但有安全边界
Layer 4: 扩展系统 目标: 开放生态但可治理
Layer 5: 记忆系统 目标: 长期记忆但控制隐私和成本
Layer 6: 安全治理 目标: 本地执行但可审批、可审计、可回滚
这六层不是"画得好看"的分层，而是产品工程里的责任边界：UI 不直接执行世界动作，Agent 不直接绕过权限，工具输出不直接淹没上下文，记忆不无脑塞进 prompt，扩展不天然可信，所有高风险动作都需要留下证据。
🤖 Agent 角色分工
不同产品会有不同的内部 Agent 数量和命名。教程不要求你死记数字，真正值得学的是分工方法：
| 类别 | 职责 | 典型模型槽位 | 工具权限 |
|---|---|---|---|
| 主 Agent | 面向用户，做最终决策和交付 | craft | 完整但受权限控制 |
| 通用子 Agent | 承接可隔离的探索、分析、规划任务 | default | 继承或受限 |
| 轻量辅助 Agent | 记忆筛选、Hook 评估、内容分析 | lite | 通常无工具 |
| 压缩/摘要 Agent | 上下文压缩、标题、会话总结 | default/lite | 通常无工具 |
设计原则是三句话：最小权限，不需要工具的 Agent 不给工具；成本匹配，轻任务交给便宜模型；上下文隔离，子 Agent 的完整推理不要直接污染主窗口。
🔄 SubAgent 通信
模式 A: asTool 函数调用
主 Agent -> 子 Agent -> 返回高密度结果
模式 B: Team 黑板协作
多个 Agent -> 共享 TaskList / Plan / 状态摘要 -> 各自认领和回写
asTool 适合"帮我探索这个目录""分析这段代码""给一个计划"这类可封装任务；Team 更适合长任务，把多个 Agent 的状态写到共享黑板，而不是让它们互相发送无限消息。关键点是：主 Agent 最好只看到结果、状态和摘要，而不是每个子 Agent 的全部思考过程。
⚡ 三大根本矛盾
| 根本矛盾 | 直接后果 | 对应机制 |
|---|---|---|
| 上下文有限 vs 信息无限 | 工具输出、历史、记忆和 schema 会挤爆窗口 | 延迟加载、输出外部化、JSONL、压缩、记忆筛选 |
| 自主执行 vs 安全可控 | Agent 越有用，越像本地执行系统 | 权限 hooks、沙盒边界、请求头、审计 hash chain |
| 模型成本 vs 任务复杂度 | 全部用最强模型成本太高，全部用轻模型质量不稳 | lite/default/craft 路由、多 Agent 分工 |
24 章其实都在回答这三件事：怎么让有限上下文承载无限工作，怎么让自主 agent 不越界，怎么把不同模型和不同 Agent 放到正确的位置。
代码架构图
flowchart LR
A["Learner"] --> B["24 Lessons"]
B --> C["mini_workbuddy"]
C --> D["tests / verify.py"]
D --> E["Clean-room Tutorial"]
📚 学习路径
| 阶段 | 章节 | 你会搭出来什么 |
|---|---|---|
| Agent 基础 | s01 - s04 | 循环、工具分发、延迟加载、权限 hook |
| 桌面运行时 | s05 - s09 | Electron 分层、sidecar、session、模型路由、JSONL |
| 记忆系统 | s10 - s12 | 工作区记忆、用户记忆、远端 profile/search |
| 上下文管理 | s13 - s15 | 大输出外部化、压缩、prompt 组装 |
| 扩展生态 | s16 - s18 | Skills、MCP connectors、Experts |
| 产品化能力 | s19 - s24 | 可视化、交付、SQLite、自动化、安全审计、综合版 |
更细的模块划分见 Chapter Map。每章代码如何继承上一章、只新增一个核心机制，见 Progression Contract。外部资料的推荐阅读路径见 Further Reading Map。对标 learn-claude-code 后的代码质量取舍见 Code Quality Review。
📖 章节目录
| 章节 | 主题 | 关键机制 |
|---|---|---|
| s01 Agent Loop | 一个循环就是 agent 的心脏 | while True / tool_use / tool_result |
| s02 Tool Dispatch | 工具注册和分发 | dispatch map / 并发工具 |
| s03 Deferred Loading | 工具按需展开 | ToolSearch / DeferExecuteTool |
| s04 Permission Hooks | 先划边界，再给自由 | permission rule / hook evaluator |
| s05 Electron Shell | 一个进程不够，要分层 | main / renderer / preload |
| s06 Sidecar Server | 主进程不跑 agent | local RPC / sidecar lifecycle |
| s07 Session Management | 每个会话独立管理 | session create/load/resume |
| s08 Model Routing | 用模型管理模型成本 | lite / default / craft |
| s09 JSONL Transcript | 追加写入，崩溃可恢复 | event log / replay |
| s10 Workspace Memory | 每天的工作要记下来 | append-only workspace log |
| s11 User Memory | 跨项目偏好放用户级 | user memory / preference distill |
| s12 Cloud Memory | 远端 profile 和历史召回 | profile injection / recall history |
| s13 Output Externalization | 大输出写磁盘，上下文留指针 | tool-result swap |
| s14 Context Compact | 上下文总会满 | truncate / prune / summarize |
| s15 Prompt Assembly | Prompt 是运行时组装出来的 | context blocks / budget |
| s16 Skills System | 技能先列目录，用到再展开 | SKILL.md / lazy load |
| s17 MCP Connectors | 外接工具要有标准协议 | discovery / trust / call |
| s18 Experts System | 领域专家整包加载 | expert pack / routing |
| s19 Visualizer | 不只是文字，还能画图 | SVG / HTML widget |
| s20 Result Presentation | 做完要交付 | artifacts / file cards |
| s21 SQLite Database | 会话、用量、任务要可查询 | WAL / schema / usage |
| s22 Automation Scheduler | 到点自动跑 | recurring / once / queue |
| s23 Audit Sandbox | 每步留痕，不可篡改 | hash chain / command policy |
| s24 Comprehensive | 机制很多，循环一个 | integrated harness |
🚀 快速开始
git clone https://github.com/adongwanai/learn-workbuddy
cd learn-workbuddy
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
先跑完全离线的章节，不需要 API key：
python3 s01_agent_loop/code.py --demo
python3 s03_deferred_loading/code.py
python3 s08_model_routing/code.py
MINI_WORKBUDDY_HOME=.tmp/mini python3 examples/mini_workbuddy_demo/code.py --mode offline
# 一次跑遍所有 harness 层（provider/session/记忆/权限/外部化/JSONL/HTTP/审计），产出 artifacts：
python3 examples/full_tour/code.py
python3 scripts/verify.py
scripts/verify.py 会覆盖：
- 所有 Python 文件语法检查
- pytest 行为测试：mini harness、REST/ACP 协议、章节 smoke、文档资产
- 离线章节 demo：延迟加载、模型路由、JSONL、输出外部化、mini harness
- 24 个章节的
--demo离线学习入口 - 离线交互模式：关键章节
--interactive能正常进入和退出 - mini HTTP server smoke
- 24 章目录、每个 README 的代码架构图、27 张配图引用、clean-room 脱敏扫描
像 learn-claude-code 一样填 key 在线跑，推荐先用 DeepSeek。每个章节都有两种入口：
python3 sXX_xxx/code.py --provider deepseek：进入章节自己的交互式教学 CLI。python3 sXX_xxx/code.py --eval --provider deepseek：跑统一的模型评测入口，写出 model/tool JSONL trace。
cp .env.example .env
# 编辑 .env，只填 DEEPSEEK_API_KEY 即可开始
python3 examples/mini_workbuddy_demo/code.py --mode real --provider deepseek
python3 scripts/run_real_smoke.py --provider deepseek --targets mini
python3 s01_agent_loop/code.py --provider deepseek
python3 s01_agent_loop/code.py --eval --provider deepseek
python3 s24_comprehensive/code.py --provider deepseek
python3 scripts/run_real_smoke.py --provider deepseek --targets all-lessons
教学章节的运行状态默认写入 ~/.learn_workbuddy/，不会碰你本机真实 WorkBuddy 的 ~/.workbuddy/。
需要指定目录时可以设置 WORKBUDDY_HOME=/tmp/learn-workbuddy python3 s24_comprehensive/code.py --provider deepseek。