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

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

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

Product Positioning

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

Decision

• 新项目创建内部默认编程 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 按账号、项目和来源会话保存话题索引与展示历史。旧本地老师话题保留原路径。停用阻止后续调用，历史仍可查看；断线按游标和持久状态恢复，重启后中断旧问题，下次提问先停止旧问题再绑定新上下文。

• Code 咨询统一使用服务端下发智能体，不内置老师／朋友角色、本地教学人设或按名称分配的工具权限。名称、头像、简介、欢迎语和推荐问题均来自发布定义；新话题使用用户选择或运营默认项，已有话题继续固定原定义和版本。所有下发项共享上述只读工具边界，通用讨论组件协议不定义智能体人格。

• 右侧咨询保留已实现的结构化讨论和主动跟进：自动检查在隐藏窗口、操作会话运行、来源归档、智能体回复或咨询草稿编辑期间延后，Main 再校验来源、启停和冷却。跟进使用同一发布定义与学生计费，不伪造学生消息。正文、保存历史和带回草稿仅接收云端主线程文本；子线程事件仍推进续传游标。带回回答只追加草稿，不自动发送。Code/Pi 执行和项目 Plugin 生命周期保持各自边界。

• 所有下发智能体以头像和名称在顶栏并排展示，点击直接切换，移除面板内的新话题智能体下拉框；数量多时在顶栏内横向滚动，不挤占窗口控件。切换恢复所选智能体的历史或空输入框，不创建话题、不发起模型调用；新话题使用所选项的当前发布版本，旧话题仍固定原版本。历史菜单保留，查看其他智能体的话题时同步顶栏选中项。

• 当前咨询历史按账号、项目保存，每轮绑定当时的操作会话；未发送草稿按账号、项目及服务端智能体 ID 分别保存。旧项目级未归属草稿折叠保留供查看，不猜测归属或自动填入其他智能体。旧客户端生成的朋友话题及草稿只读保留，不再继续调用，也不自动绑定云端智能体；旧来源会话级历史不自动迁移。现有云端 coding-teacher 契约与存储名保留为实现兼容，不构成角色分类。

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

• 咨询回答以 Markdown 渲染标题、列表、表格、代码、HTTP(S) 链接/图片和公式，代码与表格在栏内滚动；普通 JSON、Markdown 链接与代码中的字面转义保持原义。discussion-v1 仅由顶层 reply/quickReplies/tool 或专用围栏识别，组件仍遵循既有生命周期。解析失败保留原讨论卡与可恢复正文，完整 unparsedResponse 单独持久保存并默认折叠，不再次注入后续会话上下文。

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

Evidence And Release Boundary

• 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、客户端不能选老师等边界。历史实施与验证保留在源任务记录；当前机制见 产品说明。