中文 · English 一份开源教学蓝图 — 不是产品源码，是可以跑的 Agent 工程课。
模型是大脑，Harness 是操作系统。
| 📚 24章 从 agent loop 到审计沙盒 |
📐 28张图 章节与示例架构图 |
⚡ 1条命令 离线跑完整链路 |
🔌 多Provider DeepSeek/OpenAI/Anthropic |
⭐ 如果这个项目对你有帮助，请给个 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
使用 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，便于你理解完整请求链路。
No comments yet.