🔥 从0手搓桌面AI助手 · 24节课复刻WorkBuddy架构

一份开源教学蓝图 — 不是产品源码，是可以跑的 Agent 工程课。

模型是大脑，Harness 是操作系统。

⭐ 如果这个项目对你有帮助，请给个 Star 支持我们继续出课！

🤔 你是不是也被这些卡住了

你写过 CLI agent，能跑通 while True + tool calling，但一到桌面端就卡住了——工程复杂度翻 10 倍：

• 😫 会话常驻、恢复、重连 —— 不是"跑完就关"，是长期活着的进程
• 😫 工具太多时上下文窗口秒炸 —— 模型还没干活就 OOM 了
• 😫 工具输出几 MB —— 塞不进 context，模型直接摆烂
• 😫 长期记忆放哪里、什么时候注入 —— 隐私和成本两头失控
• 😫 Agent 能执行命令 —— 权限怎么设计才不变成后门
• 😫 前端、sidecar、runtime、模型、工具 —— 六层架构的每一层怎么解耦

这个仓库把这些问题拆成 24 课。每一课只新增一个机制，每一课都有一份 code.py 和一张图。

🗺️ 为什么选这个

两个项目合在一起，就是从 CLI agent 到 desktop agent 的完整工程谱系。

🧠 30 秒看懂

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 examples/full_tour/code.py

使用 Conda 管理 Python、uv 管理依赖时：

conda env create -f environment.yml
conda activate learn-workbuddy
uv sync --python "$CONDA_PREFIX/bin/python" --no-python-downloads
uv run python examples/full_tour/code.py

环境已存在时，运行 conda env update -f environment.yml --prune，激活环境后再执行上面的 uv sync 命令即可同步。项目依赖安装在 .venv，其 Python 解释器来自 Conda 环境。

这条命令会离线跑完整 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 不给工具；成本匹配，轻任务交给便宜模型；上下文隔离，子 Agent 的完整推理不要直接污染主窗口。

🔄 SubAgent 通信

模式 A: asTool 函数调用
主 Agent -> 子 Agent -> 返回高密度结果

模式 B: Team 黑板协作
多个 Agent -> 共享 TaskList / Plan / 状态摘要 -> 各自认领和回写

asTool 适合"帮我探索这个目录""分析这段代码""给一个计划"这类可封装任务；Team 更适合长任务，把多个 Agent 的状态写到共享黑板，而不是让它们互相发送无限消息。关键点是：主 Agent 最好只看到结果、状态和摘要，而不是每个子 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"]

📚 学习路径

更细的模块划分见 Chapter Map。每章代码如何继承上一章、只新增一个核心机制，见 Progression Contract。外部资料的推荐阅读路径见 Further Reading Map。对标 learn-claude-code 后的代码质量取舍见 Code Quality Review。

📖 章节目录

🚀 快速开始

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
# 轨迹蒸馏 -> 评测 -> 人工批准 -> 版本化 Skill（完全离线）：
python3 examples/self_evolving_skills/code.py --approve
# 重复失败 + 成功恢复 -> 评测 -> 人工批准 -> Reflection Memory（完全离线）：
python3 examples/reflection_memory/code.py --approve
# Skill / Memory / Reflection 检索路由评测（完全离线）：
python3 examples/retrieval_routing_eval/code.py
# Markdown 摄取、增量索引、BM25、安全门禁和可验证引用（完全离线）：
python3 examples/source_grounded_rag/code.py
# RAG + Skill/Memory/Reflection routing + S15 总预算的端到端组合（完全离线）：
python3 examples/context_pipeline_walkthrough/code.py
# 回答 Claim、引用完整性、gold source 对齐和无证据拒答评测（完全离线）：
python3 examples/answer_grounding_eval/code.py
# 分层 Memory 写入、去重、隔离、召回、压缩和跨重启恢复（完全离线）：
python3 examples/layered_memory_walkthrough/code.py
# Memory 并发、身份冲突、作用域、损坏存储与重启召回故障注入（完全离线）：
python3 examples/memory_resilience_eval/code.py
# 一次跑遍所有 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 的代码架构图、所有配图引用、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。

也可以使用 Anthropic 或 OpenAI：

# Anthropic-compatible lessons
python3 s01_agent_loop/code.py --provider anthropic

# OpenAI Responses API provider adapter（mini harness / full tour / 章节 eval 路径）
python3 examples/mini_workbuddy_demo/code.py --mode real --provider openai
python3 examples/full_tour/code.py --provider openai
python3 s01_agent_loop/code.py --eval --provider openai

# OpenAI-compatible 网关，例如 Sub2API /v1/chat/completions
OPENAI_CHAT_BASE_URL=https://your-openai-compatible-gateway.example/v1 \
OPENAI_CHAT_MODEL=gpt-5.5 \
python3 examples/mini_workbuddy_demo/code.py --mode real --provider openai-chat

OPENAI_CHAT_BASE_URL=https://your-openai-compatible-gateway.example/v1 \
OPENAI_CHAT_MODEL=gpt-5.5 \
python3 scripts/run_real_smoke.py --provider openai-chat --targets mini full all-lessons

边界说明：章节自己的交互式 CLI 多数保留 Anthropic-compatible tool_use/tool_result 形状，便于对标 learn-claude-code；统一 --eval 路径则通过 mini_workbuddy.providers 归一化 DeepSeek/Anthropic/OpenAI/OpenAI-compatible gateway，所以 24 章都能进入模型评测并写出 trace。

🧪 Mini WorkBuddy

仓库里还放了一个标准库实现的最小 harness，便于你理解完整请求链路：

MINI_WORKBUDDY_HOME=.tmp/mini python3 -m mini_workbuddy.server --port 8765

curl --noproxy '*' \
  -H 'X-Mini-WorkBuddy-Request: 1' \
  -H 'Content-Type: application/json' \
  -d '{"cwd":".","prompt":"list files"}' \
  http://127.0.0.1:8765/api/v1/runs

它包含：

• mini_workbuddy.agent: deterministic agent loop
• mini_workbuddy.tools: bash/read/tool-search + permission guard
• mini_workbuddy.storage: JSONL transcript + memory + externalized tool results
• mini_workbuddy.audit: append-only hash chain audit log
• mini_workbuddy.server: REST + ACP-like JSON-RPC
• mini_workbuddy.sidecar: session runtime 启停管理示例
• mini_workbuddy.providers: 多 provider 适配层（DeepSeek / Anthropic / OpenAI / 离线 mock）

为什么教程同时支持 DeepSeek / OpenAI / Anthropic 多 provider

learn-claude-code 用 Anthropic SDK 很自然，因为 Claude 的 tool_use/tool_result 形状和 Claude Code 教程天然贴合。但本项目叫 learn-workbuddy，重点是 桌面 agent harness，不该绑定某一家模型。所以我们做了两层适配：

• 章节路径：--provider deepseek 会把 DeepSeek 的 Anthropic-compatible API 映射成章节已有的 tool_use/tool_result 运行环境。
• mini harness 路径：Provider Adapter 把 DeepSeek/Anthropic 的 tool_use/tool_result、OpenAI Responses API 的 function_call/function_call_output、以及 OpenAI-compatible Chat Completions 的 tool_calls 归一成同一个 ToolCall/ModelTurn。

这本身就是 harness 教学的一课：loop 稳定，provider 可换。

# 离线 mock（无需 key，确定性，CI 与无 key 读者用）
python3 examples/mini_workbuddy_demo/code.py --mode real --provider offline

# 真实 DeepSeek / Anthropic / OpenAI / OpenAI-compatible gateway
python3 examples/mini_workbuddy_demo/code.py --mode real --provider deepseek
python3 examples/mini_workbuddy_demo/code.py --mode real --provider anthropic
python3 examples/mini_workbuddy_demo/code.py --mode real --provider openai
python3 examples/mini_workbuddy_demo/code.py --mode real --provider openai-chat

# 一键真实 API 冒烟（可选，需 key）
python3 scripts/run_real_smoke.py --provider deepseek --targets mini full s01 s24
python3 scripts/run_real_smoke.py --provider openai-chat --targets mini full all-lessons

真实模型 benchmark 会批量跑 DeepSeek 和 OpenAI-compatible gateway，并把成绩单、stdout 证据、JSONL 轨迹、失败改进建议写到 benchmark-runs/<name>/。默认矩阵是每个 provider 跑 mini + full + s01-s24 eval，也就是两个 provider 共 52 个 case。这是给开源读者和维护者看的"考试"，不是 CI 默认项：

DEEPSEEK_MODEL=deepseek-v4-pro \
OPENAI_CHAT_BASE_URL=https://your-openai-compatible-gateway.example/v1 \
OPENAI_CHAT_MODEL=gpt-5.5 \
python3 scripts/model_benchmark.py --providers deepseek openai-chat

# 快速检查矩阵与 trace 文件，不调用模型
python3 scripts/model_benchmark.py --providers deepseek openai-chat --max-lessons 3 --dry-run

配置见 .env.example（PROVIDER=deepseek|anthropic|openai|openai-chat|offline|auto）。协议对照与设计 说明见 docs/appendix/provider-adapter.md。

🧠 记忆系统重点

本项目把桌面 agent 的记忆拆成五层：

核心心法：上下文窗口是 RAM，JSONL、SQLite、记忆文件和 tool-results 是磁盘。

想看五类状态如何在不混淆所有权的前提下协作，可以运行完全离线的 Layered Memory Walkthrough。它直接串联 S09–S14，演示写入、重复事实蒸馏、用户隔离、带来源召回、Artifact 引用、压缩不变量和 fresh-process 恢复，不新增第二套 Memory 包。

想验证 Memory 在并发、身份冲突、跨用户读取、损坏 JSONL 和进程重启下能否 fail closed，可以运行 Memory Resilience Evaluation。它复用 S12 的公开存储与召回契约，逐 case 输出可检查证据；任何安全边界失败都不能被其他通过项平均掉。

想验证“检索正确之后，回答是否真的被证据支持”，可以运行 Answer-grounded RAG Evaluation。它把 evidence-set/citation 完整性与 fixture-backed claim/source 对齐分开评测，并覆盖无证据拒答、引用洗白和跨 query 回答重放。

🛡️ Clean-room 边界

这个仓库只包含原创教学代码和架构解释，不包含 WorkBuddy 的闭源代码、包体资源、私有 prompt、私有协议密钥或用户数据。

允许的材料：

• 公开可观察的产品行为
• 本地运行时目录的结构性观察，已脱敏
• 通用协议和开源生态知识，例如 HTTP、JSON-RPC、MCP、SQLite、Electron
• 作者原创的教学实现、伪代码和图示

不接受的材料：

• 闭源代码片段或 decompiled material
• 私有密钥、token、用户路径、用户 ID、日志原文
• 可用于绕过授权、安全机制或商业限制的细节

更多说明见 NOTICE.md 和 docs/legal/clean-room.md。

📁 项目结构

learn-workbuddy/
  images/                  # README 总图
  mini_workbuddy/          # 标准库最小 harness
  s01_agent_loop/          # 24 章课程，每章 README + code.py + SVG
  ...
  s24_comprehensive/
  docs/architecture/       # clean-room 架构说明
  docs/appendix/           # 迁移后的本地观察笔记
  docs/evidence/           # 已脱敏的证据摘要
  docs/legal/              # 公开边界和贡献规则
  examples/                # 可独立运行的小型示例
  scripts/verify.py        # 本地/CI 验证入口
  skills/                  # 示例 skill

🔗 与 learn-claude-code 的关系

learn-claude-code 更像 CLI agent harness 的起点：单进程、终端、文件系统、MCP。

learn-workbuddy 继续往桌面产品化走：多进程、sidecar、长期记忆、自动化、审计、可视化交付。

两个项目合在一起，就是从 CLI agent 到 desktop agent 的完整工程谱系。

🌟 Star History

👥 谁在学

这个板块正在收集中 — 如果你是早期读者，欢迎在 Discussions 分享你的学习笔记，我们会把你的 GitHub 头像和心得贴在这里。

💬 社区

• 📮 讨论 & 答疑：GitHub Discussions
• 🐛 Bug & 建议：GitHub Issues
• 💡 贡献代码：欢迎提交 PR，详见下方 贡献 章节

🤝 贡献

欢迎提交 Issue 和 PR，尤其欢迎：

• 修正章节中不准确或过度具体的产品表述
• 增加不依赖 API key 的离线 demo
• 改进 SVG 图和章节导航
• 增加新的 clean-room harness 机制
• 翻译成英文、日文、韩文

提交前请运行：

python3 -m pytest -q
python3 scripts/verify.py

📄 License

MIT

WorkBuddy is a trademark or product name of its respective owner. This project is an independent educational clean-room reimplementation and is not affiliated with or endorsed by WorkBuddy.

本教程基于 WorkBuddy 的架构设计与公开文档编写。代码为 Python 教学实现，非源码提取。

⭐ 如果这个项目对你有帮助，请给个 Star 支持我们继续出课！ ⭐