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

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

• Status: Accepted / implemented, amended 2026-09-23
• Date: 2026-09-22
• Approval: 用户确认项目默认 Agent、项目下会话、多老师列表与移除试聊；随后确认使用 Yuxi 原生智能体、客户端提供三个只读工具、沿用学生账号付费，并要求实施及合并。

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 续接同一问题。最多六批读取，保留原付款人、版本、上下文和截止时间；读取限当前项目，允许 .makelore/project.json，排除其余内部记录与 Git 数据，不提供本地写入或命令。
• Works Square 验证学生编程资格，使用专用短期老师凭据；聊天模型费用记入学生 ai_programming / coding_teacher 账本。老师资源仍归 Yuxi 创建者，个人 Agents 模块继续创建者付费，老师问题不占创建者个人智能体金额上限。
• 云端保存老师消息、执行和收到的片段；Main 按账号、项目和来源会话保存话题索引与展示历史。旧本地老师话题保留原路径。停用阻止后续调用，历史仍可查看；断线按游标和持久状态恢复，重启后中断旧问题，下次提问先停止旧问题再绑定新上下文。
• “问老师”仍是右侧独立答疑，用户发起，不主动巡查项目。正文、保存历史和带回草稿仅接收云端主线程文本；子线程事件仍推进续传游标。带回回答只追加草稿，不自动发送。Code/Pi 执行和项目 Plugin 生命周期保持各自边界。

Evidence And Release Boundary

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