makelore/.project-docs/10-decisions/ADR-2026-09-22-coding-teacher.md

ADR: 官方编程老师与项目会话导航

• Status: Accepted / implemented, project-scoped ongoing chat amended 2026-09-28
• Date: 2026-09-22
• Approval: 用户确认项目默认 Agent、项目下会话、多老师列表与移除试聊；随后确认使用 Yuxi 原生智能体、客户端提供三个只读工具、沿用学生账号付费，并要求实施及合并。2026-09-24 明确取消客户端固定老师／朋友分类，统一使用后端下发智能体，并要求合并上下文预算修复。

Product Positioning

2026-09-26 用户明确确认并进一步澄清：老师 Agent 是某一领域杰出人物的能力转化而成的智能体，供平台学生使用。定义以人的领域能力及学生价值为中心，蒸馏属于实现方法。能力来源、能力内涵、学生价值与真实案例验证标准集中记录在产品定位。下列云端执行、上下文读取与咨询交互决定服务于这一能力交付；客户端统一智能体模型保持。

Decision

• 2026-09-29 用户要求并授权合并可配置快捷提示。老师快捷提示由 Yuxi 的有序 teacher_shortcuts 配置拥有，每项分别保存展示文案 label 和实际提示词 prompt；最多 8 项，去除首尾空白后文案 1–40 字符、提示词 1–6000 字符。普通保存只改草稿，显式发布固定列表并以 shortcuts 下发；同一发布重试读取原快照。明确的空列表隐藏所有入口，历史快照缺字段或 null 保留客户端旧入口，未配置草稿提供可编辑的默认项。Makelore 按顺序渲染文案，点击通过普通提问发送实际提示词，聊天记录显示实际提问；目录刷新保留项目聊天和草稿。

• 2026-09-29 用户确认一次显式发布和及时刷新并授权合并。Yuxi 管理员在可管理的原生智能体编辑页一次“保存并发布”即可更新 Makelore；普通保存只改草稿。Yuxi 固定不可变快照并携同一操作身份交给 WS，只有 WS 登记提交后才报成功，失败重试不发布后来编辑的草稿。WS 按来源绑定稳定老师 ID，首次复用唯一启用旧项，歧义需显式选择；保留默认、停用和历史，不自动合并旧身份，重新启用需要显式动作。

• 前台每五秒读取小型目录 revision，进入模块及回到前台补查，变化才重新读取完整配置；后台停止轮询。刷新独立于聊天、输入和正在回答，不触发模型。Main 每次接受新问题仍读取当前版本，运行中的问题固定原版本，同项目可见聊天保持连续。 五秒是检查间隔，实际可见时间还包含网络请求，不承诺离线或故障时延迟。

• 2026-09-28 用户要求移除老师对话栏的结构化组件并确认合并；远程回复清理和恢复工作一并集成。新咨询由 Main 统一声明 {reply, quickReplies}，正文和 0–3 条可选快捷回复按所选智能体云端配置生成，客户端只提供入口事实、上下文与输出格式。超额新卡片保留正文及原文诊断，不截断或展示；历史卡片数量不改写。旧组件状态和快照作为不透明档案保留，不恢复交互、主动导入或进入模型上下文，旧组件修改路由已移除。 结果不确定的旧请求保留请求 ID、问题、引用与来源，客户端重试移除退役组件字段，Main 按已有请求身份返回结果，避免重复执行。

• 2026-09-28 用户确认像微信联系人一样持续聊天，随后明确纠正：不同项目必须有不同会话，并授权修复及合并。唯一可见聊天身份为账号＋项目＋稳定 config_id；同一项目不按名称、默认标记、Pi 会话或发布版本创建第二个可见聊天。项目隔离历史、草稿、已读和模型上下文；本次范围为本机持久化，不含跨设备同步。

• 新项目创建内部默认编程 Agent 并保存 defaultAgentId，会话直接列在项目下。打开项目不自动创建空会话，首次发送或显式新建才创建；历史 Agent ID、配置和 Pi 会话绑定保留。

• Yuxi 拥有老师提示词、模型和所选 Skills、知识库、MCP、子智能体。Works Square 运营菜单首先展示下发列表，添加时从 Yuxi 选择并发布当前配置，支持多位、默认选择与启停，不维护第二份提示词编辑器或试聊界面。

• Yuxi 显式发布或运营同步产生不可变下发版本。每次接受新问题使用当前已下发版本，运行中的问题保持原版本；版本变化不另建可见聊天。配置与资源绑定固定，Skill 按问题建立运行快照，知识内容和远端工具仍由各自服务拥有；资源撤销可能阻止执行，版本不表示复制全部外部资源。

• Yuxi 原生 Request/Run、PostgreSQL checkpoint 和 Redis 事件拥有云执行。Main 冻结本次账号、项目、来源 Pi 已完成分支的公开消息及老师话题，通过三个只读工具提供目录、UTF-8 文件行段和会话原文。文件按读取时内容提供，会话按本轮快照读取，不上传完整工程、Pi 原始日志或思考。

• 本地工具只交给老师主线程：云端持久中断完整批次，Main 主动回传配对结果，关联 Run 续接同一问题。用户于 2026-09-27 授权改造读取工具：声明 read_protocol=2 的客户端支持按层目录与连续原文分页，每问题最多 12 批、成功结果累计 64 KiB、单页 8 KiB，剩余不足 512 字节时收尾；旧客户端保持六批。最后结果消费后显式禁止继续选工具并要求基于已有证据回答。保留原付款人、版本、上下文和截止时间；读取限当前项目，允许 .makelore/project.json，排除其余内部记录与 Git 数据，不提供本地写入或命令。

• Works Square 验证学生编程资格，使用专用短期老师凭据；聊天模型费用记入学生 ai_programming / coding_teacher 账本。老师资源仍归 Yuxi 创建者，个人 Agents 模块继续创建者付费，老师问题不占创建者个人智能体金额上限。

• 云端保存执行线程、消息和收到的片段。Main 在 userData/agent-conversations///projects/ 保存轻量聊天索引和独立轮文件；每页50轮，流事件只更新当前轮。Host API 统一使用 /api/coding/projects/:projectId/agent-conversations/:agentId，历史、发送、SSE、停止、保存和已读均绑定该项目。轮文件先于索引原子保存，恢复不重发模型。停用阻止后续调用，历史仍可查看；重启将未完成问题标为中断，下次提问先停止旧问题。

• 每轮冻结项目、Pi 来源、发布版本及只读范围。同一项目相同来源／版本沿用内部 Yuxi 线程，来源或版本改变、或首轮从旧讨论协议升级到 reply-v1 时开启内部执行段，只携带该项目有预算的公开近期交流；可见聊天保持连续。切换项目恢复另一个独立聊天，不能复用跨项目云端 checkpoint。历史消息按当前项目聊天内的 ID 读取，Pi 与项目配置仍归项目所有。

• Code 咨询统一使用服务端下发智能体，不内置老师／朋友角色、本地教学人设或按名称分配的工具权限。名称、头像、简介、欢迎语和推荐问题来自发布定义。所有下发项共享上述只读工具边界，回复格式协议不定义智能体人格。

• 历史结构化讨论和快照保留在其原档案中，不参与新回复或项目聊天导入。正文、历史和带回草稿仅接收云端主线程文本；子线程事件仍推进续传游标。带回回答只追加原项目／Pi 来源的草稿，不自动发送或改写其他来源。已下发智能体的旧 Renderer 定时跟进停止派发；独立 Main 主动观察仍未合入，后续必须并入对应项目的同一聊天。

• 所有下发智能体以头像和名称在顶栏并排展示，溢出横向滚动。点击恢复当前项目中的唯一聊天或空态、独立草稿和未读，不调用模型；移除新话题加号和话题下拉框。最近50轮先加载，历史分页与流事件按请求身份合并；切换项目或智能体保留各自窗口内阅读位置，已读位置由 Main 持久保存，迟到的读取和事件不得填入另一项目。

• 2026-09-28 远程刷新与界面改动合并：顶栏手动刷新只读共享下发目录和配置，更新联系人资料，不重建聊天、不切换选中智能体、不清空历史或草稿；已接受问题保留原版本，下一轮由 Main 固定当前发布版本。停用后保留原聊天但禁止发送。发布介绍在顶栏悬停／聚焦显示，点击当前入口或 Escape 收起咨询栏，边缘调宽保留；不再显示重复面板标题栏或下发智能体新话题入口。追加问题使用三色卡片。

• 未发送文字草稿按账号／项目／智能体保存；明确引用仍携带项目／Pi 来源，来源切换后须移除旧引用或恢复原上下文才能发送。旧全局草稿仅由其记录的项目接纳，优先于更早的项目话题草稿；原记录保留。旧全局聊天依据每轮 request.projectId 或 origin.projectId 分入对应项目，保留原请求身份、映射项目已读位置，并开启新的云端执行段；原讨论状态仅留在原档案。导入可在中断后幂等续接，原始索引和轮文件不修改，无法证明项目的轮仅留在原档案中，不猜测归属。

• 更早的话题仅在已登记项目、账号与 config_id 归属均明确时导入，以项目／话题／请求来源去重，重复正文不去重；失联目录稍后重试。无法证明身份的朋友／旧老师历史及旧草稿只读保留。现有云端 coding-teacher 名称不构成角色分类。独立主动观察后续也必须向相应项目的唯一智能体聊天投递建议。

• 输入预算在编译时计入完整执行请求。本地旧模型路径按约 2 UTF-8 字节估算 1 Token，工具定义、调用和读取预留纳入同一计量；估算不替代模型上限或实际 usage。云端以完整 JSON 转义后的 query 字节数裁剪来源节选，原文仍可按 ID 读取。固定配置／当前讨论超限与用户问题／引用超限分别提示，不静默修改发布预算、问题、明确引用或话题版本。

• 咨询回答以 Markdown 渲染标题、列表、表格、代码、HTTP(S) 链接／图片和公式，长内容在栏内滚动；普通 JSON 和代码保持正文。兼容旧 {intro, questions} 和含 tool 的输出，只提取正文和快捷回复。完整正文可从保留原文中在本地恢复；无法确认完整时显示缺失提示，由用户明确点击重新回答，保持原问题、引用和项目／Pi 来源，保留现有草稿，采用当前发布版本。被动恢复不调用模型或改写已完成原始轮文件；不完整回答和未解析原文不进入后续模型上下文。 原文默认折叠、按字面展示。

• 工具活动使用实际主线程事件及 Main 本地读取结果的名称/状态，按 run/call 关联与去重，单独折叠展示；参数、输出、错误原文与推理不进入活动 DTO 或回答。未观察到结果的调用明确显示结果缺失，不补写过期事件或旧话题。Yuxi chat_service 保证只有 AI 角色进入回答流，客户端不按内容外形猜测清洗。

• 输入为空时显示暖黄色“继续看看👀”，输入后隐藏；点击才发起求助。进入咨询立即收起静态欢迎语并按账号／项目记住，真实未读建议保持显式查看／收起边界。

Evidence And Release Boundary

• 2026-09-29 目录刷新源通过 208 项相关单测、类型/lint/Vite 构建及独立审查；合并保持产品与测试源一致。WS 先升级 20260929_0099 和 revision/发布接口，再更新 Yuxi 与客户端；无本次客户端数据迁移。以下旧发布记录为历史，不代表当前 WS migration head。见本次集成。

• 2026-09-28 组件移除源 317def7912 无冲突快进合入本地 main。47 项相关单测、12 项浏览器布局、1 项 Electron 咨询场景及类型／lint／构建通过；产品与测试保持源字节，沿用其验证。没有服务端或历史数据迁移；未推送、打包或更新安装版。见源任务和集成记录。

• 2026-09-28 项目隔离修复源 4b41c23a3a5e9da1a329b1b69930787a670163de 已合入本地 main，纠正上述原跨项目假设。382 项相关测试、标准 typecheck、变更文件 lint、Vite 构建和 3 项 Electron 场景通过，覆盖同一智能体的双项目历史／草稿切换、升级导入及目录刷新；扩展 Main 仍有 66 项既有诊断。合并保持产品／测试与已验证源一致，沿用源证据；没有更新安装版或验收线上模型。见修复源记录与续接集成记录。

• 2026-09-28 单会话源 7aa81da616449dead25557476cf4f1433edf84b5 已纳入本地 main。源365项相关单测、Renderer typecheck、变更文件 lint、Vite构建和真实 Electron 夹具交互通过；扩展 Main 检查与基线同为66项既有诊断。合并保持产品／测试与源一致，不重跑相同验证。未推送、打包、部署或进行真实付费模型验收；主动观察组合验收另行完成。见源任务及集成记录。下方旧话题交互证据仅记录当时版本。

• 2026-09-24 用户明确要求多智能体在顶栏铺开并授权合并，客户端源 a10cf000157a1a3edcfad43705e0824f19568a33 已快进纳入本地 main。源相关单测、17 项浏览器布局和 1 项 Electron 夹具交互、类型／lint／构建通过，具体分批验证见源记录。合并未改变已测产品字节；不代表已更新安装版或真实供应商验收。

• 2026-09-24 渲染源 97837cef90baf6bb02cfda0cef7b938081f3c5f7 与 Yuxi 配套源 02f27f33a8b816589036503f0720d446418c28aa 已纳入本地主分支集成。客户端源 287 项单测、12 项真实浏览器布局用例及独立审查通过；Yuxi 82 项相关协议回归与真实 LangGraph 确定性模型测试通过。浏览器接口为替身，不代表安装版或线上模型已验收；旧版已覆盖的失败原文无法恢复。

• 2026-09-24 客户端源 8a157be4f62d073744164318e02185aebeaadc09 包含预算修复 de72b1cd945df373d09402a1cf3a0e9b34832f03。预算修复通过 289 项相关测试；统一智能体覆盖 323 项相关用例、类型／lint／生产构建、2 项 Electron 交互和 13 项布局测试。扩展 Main 类型检查仍有基线 66 项诊断，无新增；不代表真实收费模型、已安装客户端或生产整链验收。详见两份源任务记录。

• 配套源：Works Square 79b1da574364d6f412e4395c179b5d27cc7bbd7d；Yuxi c2792dc4938a68db8ce1e34056e84af4b06c739b；MakeLore d20c818fe79bc5833cef15d99974b699dde71c6d。

• 源验证包括 WS 66 passed / 1 skipped、Operations 125 项及构建/浏览器验证；Yuxi 2243 passed / 1 skipped、真实 HTTP/PostgreSQL/Redis/worker/SDK 续接验证；MakeLore 51 项相关测试、typecheck、lint、构建及已有 Electron 流程验证。模型使用明确替身，真实供应商扣款与完整生产拓扑未验收。

• 合并不代表部署；需配套发布三个端及 Yuxi worker。本次无新增数据库迁移，WS 唯一 head 仍为 20260922_0096。老师模型必须在学生网关开放，既有云接入配置与被选资源依赖须就绪。

• 本修订取代旧 Main 独立模型循环、云端不存老师消息、纯文本 Skill、客户端不能选老师等边界。历史实施与验证保留在源任务记录；当前机制见 产品说明。