adongwanai/learn-workbuddy

解决的问题

构建桌面AI助手比命令行代理困难得多。一个简单的循环调用工具在终端中可以正常工作，但桌面应用必须在会话之间保持存活，在不会撑爆上下文窗口的前提下管理庞大的工具输出，安全地存储长期记忆，控制权限以防止代理成为后门，并分离数十个移动部件。这个项目将这些难题转化为24个结构化的课程，每节课都通过可运行的Python代码和图表添加一个确切的机制。

工作原理

这个项目是一个教学蓝图，而非生产源码。它将桌面代理分解为六个层次：UI、代理推理、工具执行、扩展系统、记忆系统和安全治理。每节课（s01到s24）都建立在前一课的基础上，一次添加一个核心机制——从基本的代理循环、工具分发和权限钩子，到Electron外壳、边车服务器、会话管理和模型路由，再到JSONL转录、工作区/用户/云记忆、输出外化、提示词组装、技能、MCP连接器、专家、可视化、SQLite、自动化和带哈希链的审计沙箱。

包含了一个名为Mini WorkBuddy的最小参考实现——仅使用Python标准库构建——以便你可以检查完整的请求路径：代理循环、带权限保护的工具、JSONL存储、外化输出、追加式审计日志、REST/ACP类服务器，以及一个将DeepSeek、Anthropic、OpenAI和OpenAI兼容网关统一到单个ToolCall/ModelTurn接口的提供者适配器。

你可以通过执行每章的code.py并带上--demo标志，在完全离线的情况下运行许多演示（无需API密钥）。对于真实模型课程，你可以填入DEEPSEEK_API_KEY（或Anthropic/OpenAI密钥），并运行交互式教学CLI或统一评估模式，这些模式会写入模型/工具JSONL轨迹。scripts/verify.py会检查语法、测试、离线演示、文档和洁净室合规性。

适合谁

适合已经理解基本CLI代理（如相关的learn-claude-code项目）并希望更深入桌面产品工程的开发者——学习如何架构长时间运行的进程、管理记忆和上下文、处理多代理协作、加强安全，并与多个模型提供者集成。也适合偏好动手实践、逐章学习且依赖最少的教师和自学者。

亮点

• 24章，包含可运行的Python代码和28张图表，每课只添加一个机制
• 六层架构显示职责边界：UI、推理、工具、扩展、记忆和安全
• 通过提供者适配器层支持多提供者（DeepSeek、Anthropic、OpenAI、OpenAI兼容网关）——循环保持稳定，模型可以交换
• 大多数示例完全离线演示，包括标准库Mini WorkBuddy工具，任何人都可以在没有API密钥的情况下运行和检查完整流水线
• 详细记忆系统分为五层（工作区、用户、远程配置文件、转录、工具结果交换），关键思想：上下文窗口是RAM；JSONL、SQLite、记忆文件和工具结果是磁盘
• 洁净室保证：仅包含原始教学代码和公开的架构观察，绝不包含WorkBuddy的闭源代码、密钥或私有提示
• 包括高级示例评估，如记忆恢复力、基于证据的RAG、检索路由，以及一个可以跨所有课程比较提供者的模型基准