学伴 Agent
用可运行原型验证学习引导、教材工具、Memory 与 Agent 行为边界
先判断学习意图与会话状态，再进入对应技能；工具结果经过校验后才用于回复，评测同时关注“该调用”和“不该调用”。
拍照后形成可检查的题目清单，支持 AI 切分、手动标注、原图对照和逐题讲解状态，而不是把整张图片直接交给模型一次作答。
学伴将《声音的产生与传播》转成四项顺序解锁的学习挑战，让预习从一次回答变成可继续的任务过程。
思维导图以确定性教材检索为事实来源，再由 Agent 组织知识结构并支持后续追问。
为什么做
在工作中准备提出 AI 学伴需求时，我发现很多关键问题无法靠流程图回答：学生拍下一道题后，系统应该直接讲解还是先判断是否已经作答；学生连续索要答案时，Agent 怎样既不对抗又保护学习过程；课本知识、历史对话和长期记忆分别在什么时候进入上下文；工具失败或证据不足时，最终回复如何诚实降级。
因此，我没有先写一份理想化 PRD，而是先做了学伴 Agent。它是一个可运行的产品预研原型，目标是让产品、算法和研发能够看到真实对话、状态变化和失败模式，再决定正式产品需要什么能力与边界。
从聊天框扩展为学习工作台
学伴 Agent 最初从自由讨论开始，随后逐步形成多种可切换、可继续的学习形态：
- 自由讨论：判断是否需要教材、记忆或互动资源，不需要工具时直接回答。
- 拍照讲题：识别一张图中的题目结构，形成题目清单，再逐题进入引导式讲解。
- 课本预习：定位指定教材内容，生成 3—5 个顺序解锁的学习任务，并保存进度。
- 思维导图：基于课本证据生成知识结构，支持从脑图内容继续追问。
- 会话与数据视图：保留多会话、对话摘要、学习洞察、长期记忆以及每轮 Token / 调用信息。
产品形态的变化很重要：学习 Agent 不只是消息气泡。题目清单、任务卡、脑图、图片标注与会话状态都是学生理解“系统正在做什么”的界面证据。
拍照讲题：先理解学生处于哪一步
“上传题目—模型给答案”实现很快，但教育价值有限。我将拍照讲题拆为题目摄入、题目切分、选择当前小题、识别学生状态、提取知识要点、逐轮评估覆盖度和结束讲解。
系统需要区分未作答、已有草稿、补充材料、新题和无关图片。面对未作答学生，首轮重点是找到最小可行动提示；面对已提交解答的学生，重点转为检查思路和定位错误。学生卡住时可以提升提示强度，但不能因为连续索要就直接替答。
这让我把“苏格拉底式教学”从一句 Prompt 变成可观察的产品状态：当前题目、学生参与姿态、提示等级、已覆盖知识点和讲解退出条件都需要被记录与验证。
教材工具：RAG 不是默认答案
原型中既有向量检索，也有按教材结构获取 OCR 原文的工具。实践后我明确了边界：对于课本预习、思维导图和指定页码问题，主路径应该是确定性的 fetch_textbook；向量检索只能作为辅助召回，不能用“语义相似”替代具体教材事实。
工具结果还需要判断 usable、missing parameters、wrong target 或 irrelevant。找到文本不等于找对内容；证据不可用时，Agent 应该补充参数、澄清目标或透明说明，而不是用训练记忆补齐一个看似流畅的回答。
Memory：保留什么比记住更多更重要
我把记忆区分为短期对话上下文、可复用的长期事实和对话后形成的学习洞察。长期事实必须有来源、作用域和可纠错机制；一次对话中模型生成的推断不能自动升级为稳定事实。
这也改变了评测方法。Memory 不只检查“能否召回”，还要验证不该写入时是否保持克制、重复信息是否去重、冲突如何处理，以及最终回答是否真的使用了被检索到的证据。
在重构前先冻结产品行为
当原型从多个独立流程演进到统一 Agent Runtime 时，我没有直接用新架构替换旧实现，而是先盘点 F01—F23：每项能力对应的入口、API、SSE 事件、存储、界面和已有测试是什么。
这次审计发现，文档中的能力表已经落后于代码；多会话、手动图片标注和 Context / CallSpan 监测都是后来增加的真实产品行为。同时，单元测试覆盖并不等于端到端行为一致，Runtime 重构还需要验证 Prompt、模型适配、事件、存储和 Web UI 的整条链路。
因此，页面不会把 Runtime V2 描述为已经完成。它更能体现我的工作方式：先建立行为基线和验收口径，再讨论架构是否更优。
我学到的技巧
1. 教育 Agent 的质量是多维约束
除了回答正确，还要测工具选择准确率、工具非调用准确率、边界纪律、参数质量、事实依据和记忆写入质量。平均正确率无法覆盖“直接替学生作答”这种高风险失败。
2. 多模态不是多传一张图片
图片会改变意图、会话和 UI：它可能是新题、学生解答、补充材料或无关内容。可靠流程需要先识别图片在当前会话中的角色，再决定是否切题、继续讲解或请求确认。
3. 把开放式生成包在确定性骨架里
教材定位、题目状态、工具执行、结果校验和会话持久化适合由确定性系统负责；模型更适合做语义判断、教学表达和局部规划。两者的边界越清楚，产品越容易调试和评测。
4. 原型的价值是暴露失败，而不是只演示 Happy Path
真实对话会出现识别错误、工具缺参、错误教材目标、学生反驳和模型过度解释。保留这些失败并追到具体链路，比制作一个永远正确的演示更有助于形成正式需求。
它证明什么
学伴 Agent 证明我能把一个模糊的“做个学习 Agent”拆成可运行的产品能力、工具与数据边界，并通过真实使用、代码审计和评测设计逐步收敛需求。它也是我从 AI 产品设计深入到 Agent Runtime、上下文、Memory 与 Evals 的代表性预研项目。
MY CONTRIBUTION / 个人贡献
- 从学习场景出发设计自由讨论、拍照讲题、课本预习、思维导图与资源推荐等 Agent 能力及路由关系
- 设计题目切分、学生状态判断、知识要点覆盖和苏格拉底式引导，明确“不直接替学生作答”的行为边界
- 区分对话上下文、长期事实、学习洞察与教材证据，参与工具、会话、SSE 状态和前端产品形态实现
- 在 Runtime 重构前建立产品 Feature、代码路径、API、存储与 Evals 的对应清单，避免用新架构替换掉已有行为
PROJECT OUTCOME / 项目结果
- 形成覆盖文本、图片、教材与多轮任务状态的可运行学习 Agent 原型
- 梳理出 F01—F23 产品能力基线；一次审计可收集 296 项 pytest 测试，但独立批量 Evals 仍需继续完善
- 将学习 Agent 的质量标准从“回答正确”扩展到工具选择、非调用、边界纪律、事实依据与记忆写入质量
口径说明：这是产品预研与工程原型，不表述为正式商业化产品；页面截图来自当前本地版本。Runtime V2 尚在未提交重构中，本文只把已实现基线与重构方法作为证据，不宣称迁移已经完成。