Knoweia：苏格拉底式 AI 编程学习桌面应用

Knoweia 的第一版由我开发。这里介绍的是 2026 年 2 月形成的桌面学习系统：学生在课程章节中与 AI 交流，在同一环境里编写和运行代码，AI 根据他们实际做了什么、看到了什么、还有哪里不理解，继续调整教学。今天的 Knoweia 官网已经有后续内容，不能将其全部视为这一版的设计。

这项设计首先需要处理一个很具体的矛盾：编程助手可以很快给出答案，但学习者需要自己完成一次理解和实践。简单要求模型“不要直接给答案”也不够。学生可能确实不理解一个概念，也可能只是少装了一个依赖；前者值得追问，后者如果仍然绕着提问，会把本来可以立即解决的障碍变成挫败感。

因此，Knoweia 把教学拆成了几个可以明确描述的问题：这一章要学会什么，当前正在做哪一小步，什么证据说明已经完成，什么时候应该继续追问，什么时候应该直接帮学生解除阻塞。聊天只是学生看得见的入口，这些判断才构成课程的连续性。

一次学习，从具体行动开始

进入章节后，学生面对的是一个学习伙伴，而不是几个同时发言的 Agent。它的基本节奏是：提出一个可执行的行动，请学生报告操作与结果，再根据反馈决定下一步。例如，学习读取 CSV 时，可以先让学生找到相应函数并运行，再讨论返回的数据结构；如果只是括号没有闭合，则直接指出语法问题，修正之后回到学习目标。

提示词明确区分核心任务与脚手架任务。核心任务对应章节要培养的能力，不应由 AI 直接提供完整可运行的解答；脚手架任务包括环境配置、路径检查和测试数据准备，在允许的范围内可以给出短代码帮助。这个区别避免把所有帮助都当成“泄露答案”，也避免借排错之名替学生完成整道练习。

另一条重要规则是一回合一行动。教学回复应让学生知道现在需要尝试什么，并请求输出、错误或一句解释。遇到连续无进展或明确的挫败表达时，可以切换为一个直接的解除阻塞步骤。学生主动跳过任务，也会被单独记录为跳过，而不被悄悄计入完成。

这种交互并不把“我懂了”当作足够的完成证据。学习进展需要落到正确输出、实际操作或概念解释上。系统能记录证据，不等于已经证明学生在其他情境下也掌握了技能；它先解决的是课程内部判断依据不能只是一句自我报告的问题。

三个角色，分开处理对话、进度与记忆

学习伙伴 Companion Agent 负责对学生说话。每轮除自然语言回复之外，它还输出结构化的回合结果：学生尝试了什么、观察到了什么、遇到的是环境障碍还是概念障碍、有哪些子任务证据，以及是否需要专家帮助。这样的结果让后续模块处理学习状态时，不必每次重新猜整段对话的意思。

路线管理器 Roadmap Manager 不直接面对学生。它根据章节任务及完成原则维护子任务状态，并向学习伙伴提供一个指令包：当前关注点、教学建议、少量检查目标、是否允许辅助代码，以及指令何时可以更新。把这个角色分出来，是为了避免一个模型在友好对话的同时，随意改变课程目标或过早判断任务完成。

指令包也不是每轮全部重写。系统通过 lock_until 等条件保留当前教学方向，只有达到检查点、出现新的阻塞或满足特定条件时才解锁调整。这样，学生刚开始尝试一个动作，下一轮不会因为措辞变化就被带到另一个方向。

备忘录 Agent 维护动态学习报告、错误记录与精简摘要。报告区分当前主任务、这一任务下的具体进展、后续任务与跳过项；错误记录关注具有教学价值的概念误解和重复的编码错误。摘要则把关键观察、困难与阻塞类型反馈给路线管理器。对话历史还按近期、中期与长期组织，减少长会话完全依赖原始聊天记录的问题。

三者之间传递的并非三份独立意见，而是可以检查的对象：回合结果、指令包、任务状态与报告。学生只需保持一条对话，系统内部则保留“为什么继续这一步”的依据。

专家检查应当改变教学，而不只是多生成一段文字

有些判断需要检查实际材料。例如学生上传了数据文件，是否满足当前练习要求，不能只根据文件名回答。章节可以声明可用专家、咨询场景与约束规则；路线管理器在需要时调用专家，再把发现转成后续教学指导。

设计文档中的一个例子是数据适用性检查：练习要求至少一定数量的记录和指定字段，学生上传的文件不符合要求，专家返回不适用及阻塞原因。相应规则会约束任务推进，并将当前目标调整为修正数据或采用课程样例。这里的记录数和字段属于具体课程条件，不是所有学习任务共用的标准。

专家因此不是聊天框旁边的另一个机器人。它的输出进入课程控制过程，既可以提供解释，也可以阻止缺少必要条件的下一步。与此同时，简单问题不必都转交专家；否则每次提问都增加一轮模型调用，也会让教学节奏变得沉重。

桌面端为什么有一个本地 Sidecar

系统由三个仓库组成：桌面端、本地 Sidecar和后端。它们分别承担交互与本机资源管理、教学运行时、账户与课程分发。

Electron 桌面端展示课程、聊天、代码编辑和执行结果；主进程管理文件、下载及 Sidecar 生命周期，通过受限的桥接接口向界面提供能力。Python Sidecar 运行教学编排、会话记录和代码相关服务。云端 FastAPI 后端负责登录、选课、章节权限、版本登记、进度和同步数据。模型请求仍然涉及所配置的模型服务，本地运行时并不意味着模型推理离线完成。

这种拆分与编程学习的实际操作有关。代码、数据文件、Notebook 状态与运行输出需要留在一个可持续使用的工作区里，而非每轮重新粘贴进聊天框。代码编辑器将运行结果带回教学上下文，Sidecar 还能取得最近执行记录，让 AI 看见学生的实际尝试。

设计还区分学生代码与专家执行：学生代码需要保留工作区和连续执行状态；专家工具应在更受限的临时空间、权限和工具范围内运行。超时、输出上限与取消机制用于控制执行，不能把这些限制泛称为已经获得完整的安全隔离。

课程是一组可更新的教学材料

章节内容没有全部写死在桌面程序里。一个章节包包括背景说明、任务列表、任务完成原则，也可以覆盖交互协议、教学方式及专家咨询配置。后续的包格式又加入脚本、数据集和图片资源，使课程不仅是一段提示词。

这种组织方式让课程作者能分别调整“教什么”“什么算完成”和“怎样帮助学生”。例如改变完成标准，不一定需要改桌面界面；增加检查数据的专家，也可以作为课程资源更新。通用教学规则有默认值，章节可以提供更具体的覆盖。

桌面端按版本下载不可变的 bundle，检查完整性与兼容要求，再切换当前使用版本。体积较大的 Python 运行环境、经常调整的 Agent 规则、专家和章节内容采用不同更新单元。这样修正一处课程说明，不必让学生重新下载整套运行环境；而版本和校验信息又保留了问题追溯的依据。

换一台电脑，保留的不应只有进度条

早期云端进度只能说明某章到了哪里，无法恢复学生如何走到这里。后续同步设计因此增加了对话轮次、最新教学记忆和动态报告，以及用户主动提交的代码与 Notebook 文件。

桌面端先向后端登记会话，再把会话身份交给 Sidecar。每轮完成后，由 Sidecar 尝试同步本轮对话、记忆和报告；同步失败不阻塞当前学习。新设备打开章节时，可以取得已同步状态并重新接上会话。工作区文件则通过单独的提交过程保存，不能将这种恢复理解为整台电脑的自动镜像：专家内部咨询、上传的数据集和完整执行历史不在该版恢复范围内。

这一选择保留了本地学习的连续性，也承认云端同步与教学主流程的不同优先级。学生正在思考和运行代码时，不应因为一次同步失败被迫停下来；但系统需要明确保存了哪些状态，才能在下次打开时提供有依据的延续。

Knoweia 的第一版围绕的始终是同一件事：让 AI 的下一句指导，与学生刚刚做过的事发生关系。课程任务提供方向，代码运行提供观察，进度管理保留判断，记忆与报告让这些判断能够延续到后面的学习。