learn-workbuddy: a 24-chapter Python tutorial that rebuilds a desktop AI agent harness
从 0 复刻 WorkBuddy-style 桌面 AI 助手 Harness：24 章 Python 教程，覆盖 Agent Loop、工具调用、记忆系统、Sidecar、沙盒审计、DeepSeek/OpenAI 评测轨迹
At a glance
- What is it?
- The repository is a clean-room teaching blueprint, not a product. It walks from a bare while True agent loop to a sidecar runtime, layered memory, output externalization and an audit sandbox, with one new mechanism per chapter.
- Who is it for?
- Adopt it if you already have a working CLI agent and want to understand what changes at the desktop layer: sidecar lifecycle, permission hooks, memory tiers, output externalization and audit. Skip it if you want a library to import into production, or a working desktop assistant you can install today; the repository is teaching code and its own comparison table calls the direct WorkBuddy experience a black box.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What problem learn-workbuddy solves, and for whom
The README frames the gap bluntly: you can write a CLI agent with a while True loop and tool calling, but moving that to the desktop multiplies engineering complexity. The listed pain points are specific. A desktop session is a long-lived process that must survive reconnect and restore, not a script that exits. Tool schemas and outputs can blow the context window before the model does any work. Tool output measured in megabytes does not fit into context. Long-term memory raises privacy and cost questions about where it lives and when it is injected. An agent that executes commands needs a permission design that does not become a backdoor. Six layers (frontend, sidecar, runtime, model, tools, storage) have to be decoupled.
The repository answers with 24 chapters, each adding exactly one mechanism, each with a code.py and a diagram. The stated audience is engineers who want to understand desktop agent architecture from the inside. The README's own comparison table places learn-claude-code as a CLI agent starting point and the real WorkBuddy as a closed product, positioning this repo between them as the desktop engineering system with visible code. That is a fair description of scope. It is not a framework, and nothing in the README suggests you should ship it.
The agent loop is chapter one, the harness is the other twenty-three
The repository's central claim is that the model is only the brain and the harness is the operating system. The architecture diagram makes the data flow explicit: Desktop UI to Preload and IPC bridge to Main Process to Local App Server to Sidecar Manager to Session Runtime over an HTTP or ACP-like protocol, then into the Agent Loop, which reaches the Tool Registry, the Memory System, Persistence and the Safety layer. Tools also pass through Safety, and Memory writes to Persistence.
The chapter list follows that diagram in order. s01_agent_loop covers while True with tool_use and tool_result. s02_tool_dispatch adds a dispatch map and concurrent tools. s03_deferred_loading introduces ToolSearch and DeferExecuteTool so tool schemas expand on demand. s04_permission_hooks adds permission rules and a hook evaluator. From s05 to s09 the repo builds the desktop runtime: Electron main, renderer and preload separation, the sidecar server, session management, model routing and a JSONL transcript. s10 through s15 handle memory and context: workspace memory, user memory, remote profile and search, output externalization, compaction and prompt assembly. s16 to s18 cover the extension surface (Skills, MCP connectors, Experts), and s19 to s24 cover visualization, result presentation, SQLite, an automation scheduler, the audit sandbox and a comprehensive build.
The README states that each chapter inherits the previous chapter's code and adds a single core mechanism, and points to docs/progression-contract.md for that contract. That constraint is the most interesting design decision here. It makes the repository readable as a sequence rather than as a pile of examples, and it means any chapter can be diffed against the one before it.
Installing learn-workbuddy and running the offline full tour
The README gives a three-step path with a virtual environment, then a single command that exercises the whole chain. The requirements file pins the teaching dependencies: anthropic, openai, python-dotenv, pyyaml and pytest. SDKs are imported lazily, but the README's comment in requirements.txt says installing them up front keeps the clone-and-run promise true.
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 examples/full_tour/code.pyAccording to the README, that last command runs the full harness tour offline: provider adapter, session, memory, tools, permissions, externalization, JSONL, HTTP, audit and artifacts. No API key is required for the offline path, because the adapter falls back to a deterministic mock provider. If you use Conda for Python and uv for dependencies, the README documents a second path:
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.pyThe README notes that dependencies land in .venv while the interpreter comes from the Conda environment, and that an existing environment is updated with conda env update -f environment.yml --prune before rerunning uv sync. To point the harness at a real model, copy .env.example and set PROVIDER. The example file documents deepseek, anthropic, openai, openai-chat, offline and auto, where auto tries anthropic, then deepseek, then openai, then openai-chat, and otherwise falls back to offline. DeepSeek is described as the recommended learning path and uses an Anthropic-compatible endpoint with DEEPSEEK_API_KEY, DEEPSEEK_MODEL and an optional DEEPSEEK_BASE_URL. The same file lists MiniMax, GLM and Kimi under Anthropic-compatible providers with their own MODEL_ID and base URL columns.
Where the tutorial stops being a product
The README says it directly: this is an open teaching blueprint, not product source code. That single sentence disqualifies a whole class of expectations. There is no packaged desktop application to download, no installer, no supported upgrade path, and no release history in the repository metadata. If you need a working assistant on your desktop today, this is the wrong repository, and the README's own comparison table says so by listing the real WorkBuddy under product usage.
A second limitation is language. The badge list marks the project as Chinese, and the README, chapter map, progression contract and further reading map are written in Chinese. The Python identifiers and file names are English, so the code is readable, but the reasoning behind each chapter lives in prose you have to read in Chinese. That is a real cost for an English-speaking team evaluating the repo.
The third constraint is the one-mechanism-per-chapter contract itself. It is excellent for learning and awkward for reuse. A chapter's code.py is shaped by the pedagogical step it represents, so lifting s13_output_externalization into a production pipeline means understanding what the chapter deliberately left out. The repository points to docs/code-quality-review.md, which it describes as a review of code quality trade-offs made against learn-claude-code. Read that before you plan to copy anything.
learn-claude-code and the real WorkBuddy as the two reference points
The README names two alternatives and describes the difference in approach rather than just the name. learn-claude-code is characterized as a CLI agent starting point: single process, terminal, MCP, Anthropic only, with partial offline support. learn-workbuddy targets the desktop layer instead: sidecar, memory, audit and automation, with DeepSeek, OpenAI and Anthropic all supported and an offline demo path that needs no key. The README's framing is that the two projects together form a spectrum from CLI agent to desktop agent, which is a more useful way to present a comparison than a feature table alone.
The second reference point is WorkBuddy itself. The README treats it as a closed product you can only experience as a black box, and the repository's clean-room badge and docs/legal/clean-room.md indicate the code was written without copying it. That distinction matters if you are evaluating licence risk: the tutorial is MIT licensed and the repository ships NOTICE.md and THIRD_PARTY_NOTICES.md alongside the licence file. The README does not claim any affiliation with the product it is modeled after, and the clean-room document is the place to check how that boundary was drawn.
Maintenance, licence and what an upgrade actually costs
The repository is not archived and the last push was on 2026-09-14. There are no retrieved releases, so the project has no versioned upgrade path to follow; you track the main branch or you pin a commit. For a tutorial that is acceptable, because the artifact you care about is the explanation, not a binary. It does mean there is no changelog telling you when a chapter's code changes under you, and no deprecation policy for the dependencies listed in requirements.txt.
The licence is MIT, which is permissive and places few obligations on reuse. Two caveats belong here without straying into legal advice. First, MIT covers this repository's code, not the product it is modeled after; the clean-room document exists precisely to keep that line visible. Second, the repository ships NOTICE.md and THIRD_PARTY_NOTICES.md, so if you vendor chapter code into your own project, read those files and keep the notices intact. The practical upgrade cost is your own: because each chapter builds on the previous one, a change to an early chapter can ripple through later ones, and the progression contract document is the map for that.
Editorial conclusion
Adopt it if you already have a working CLI agent and want to understand what changes at the desktop layer: sidecar lifecycle, permission hooks, memory tiers, output externalization and audit. Skip it if you want a library to import into production, or a working desktop assistant you can install today; the repository is teaching code and its own comparison table calls the direct WorkBuddy experience a black box. Before committing, run python3 examples/full_tour/code.py with no API key to confirm the offline path works on your machine, then read docs/progression-contract.md to check that the one-mechanism-per-chapter promise matches how you plan to use it.
Frequently asked questions
Is learn-workbuddy the WorkBuddy app, or a tutorial about it?
It is a tutorial. The README calls it an open teaching blueprint rather than product source code, and it contains 24 chapters of original Python teaching code rather than the product's code.
Does learn-workbuddy cost anything?
The repository is MIT licensed and the README states that the full tour runs offline without an API key, so no model spend is required to follow the demos. Costs only appear if you point the adapter at a paid provider such as DeepSeek, Anthropic or OpenAI.
What is WorkBuddy from Tencent, and how does learn-workbuddy relate to it?
The README treats the real WorkBuddy as a closed product you can only experience as a black box, and positions learn-workbuddy as a clean-room rebuild of its architecture for study. The repository ships a clean-room document and does not claim affiliation.
Community notes