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

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

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

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 咨询统一使用服务端下发智能体，不内置老师／朋友角色、本地教学人设或按名称分配的工具权限。名称、头像、简介、欢迎语和推荐问题均来自发布定义；新话题使用用户选择或运营默认项，已有话题继续固定原定义和版本。所有下发项共享上述只读工具边界，通用讨论组件协议不定义智能体人格。
• 右侧咨询保留已实现的结构化讨论和主动跟进：自动检查在隐藏窗口、操作会话运行、来源归档、智能体回复或咨询草稿编辑期间延后，Main 再校验来源、启停和冷却。跟进使用同一发布定义与学生计费，不伪造学生消息。正文、保存历史和带回草稿仅接收云端主线程文本；子线程事件仍推进续传游标。带回回答只追加草稿，不自动发送。Code/Pi 执行和项目 Plugin 生命周期保持各自边界。
• 当前咨询与草稿按账号、项目保存，每轮绑定当时的操作会话。旧客户端生成的朋友话题及草稿只读保留，不再继续调用，也不自动绑定云端智能体；旧来源会话级历史不自动迁移。现有云端 coding-teacher 契约与存储名保留为实现兼容，不构成角色分类。
• 输入预算在编译时计入完整执行请求。本地旧模型路径按约 2 UTF-8 字节估算 1 Token，工具定义、调用和读取预留纳入同一计量；估算不替代模型上限或实际 usage。云端以完整 JSON 转义后的 query 字节数裁剪来源节选，原文仍可按 ID 读取。固定配置／当前讨论超限与用户问题／引用超限分别提示，不静默修改发布预算、问题、明确引用或话题版本。

Evidence And Release Boundary

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