docs: 记录智能体分页读取修复集成

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

@@ -1,6 +1,6 @@
 # ADR: 官方编程老师与项目会话导航
 
-- Status: Accepted / implemented, positioning clarified 2026-09-26
+- Status: Accepted / implemented, paged reads amended 2026-09-27
 - Date: 2026-09-22
 - Approval: 用户确认项目默认 Agent、项目下会话、多老师列表与移除试聊；随后确认使用 Yuxi 原生智能体、客户端提供三个只读工具、沿用学生账号付费，并要求实施及合并。2026-09-24 明确取消客户端固定老师／朋友分类，统一使用后端下发智能体，并要求合并上下文预算修复。
 
@@ -14,7 +14,7 @@
 - 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 数据，不提供本地写入或命令。
+- 本地工具只交给老师主线程：云端持久中断完整批次，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 咨询统一使用服务端下发智能体，不内置老师／朋友角色、本地教学人设或按名称分配的工具权限。名称、头像、简介、欢迎语和推荐问题均来自发布定义；新话题使用用户选择或运营默认项，已有话题继续固定原定义和版本。所有下发项共享上述只读工具边界，通用讨论组件协议不定义智能体人格。

.project-docs/20-architecture/system-overview.md

@@ -1,6 +1,6 @@
 # System Overview
 
-云端咨询最多执行六批本地读取。Yuxi 消费最后一批结果后通过 `tool_choice: none` 请求最终答案；Main 保留第七批保护，并区分 `teacher_read_limit`、`teacher_context_expired` 和 `teacher_protocol_invalid`。真实模型与安装版验收保持独立，失败问题不自动重试。
+云端咨询的 Main 声明 `read_protocol=2`：目录按层分页（默认深度 4、最多 6，跳过生成缓存），文件与捕获会话返回连续文本及准确的下一页行／Unicode 字符列。文件增量解码，不受 UI 预览大小限制。每问题最多 12 批、累计成功结果 64 KiB、单页 8 KiB；剩余不足 512 字节时停止读取。Yuxi 消费最后一批结果后通过 `tool_choice: none` 请求最终答案，保留原身份、版本、时限与幂等续接；未声明新协议的旧客户端保持六批。工具活动以问题与逻辑 tool_call_id 合并跨 Run 重放，原始 interrupt 工具错误不单独判为失败。Main 区分读取额度、上下文失效与协议错误；失败问题不自动重试。须先更新 Yuxi API／worker，再更新客户端；生产供应商与安装版验收仍待完成。
 
 智能体图标跟随发布定义：Yuxi 将原生 `icon` 固定到发布快照，Works Square 转为公开地址 `icon_url` 下发。Makelore 顶栏、邀请、面板标题、欢迎区和消息行统一读取该字段；缺失或加载失败时回退到既有 `avatar_id`。新话题取当前发布定义，旧话题保持原版本；自定义图标使用正常图像渲染，内置像素头像保持像素样式。
 详见[图标集成记录](../30-worklog/tasks/20260926-merge-agent-avatar-ml-92dc837e.md)。

.project-docs/30-worklog/current-state.md

@@ -4,6 +4,8 @@ This file is the integrated default-branch snapshot. Feature tasks record progre
 
 ## Integrated Through
 
+- 2026-09-27：无冲突合入已独立审查源 `56cefe84e7b654bcc20f2b8fde7f97336134fec8`，包含工具活动去重 `8a74721`。三个只读工具提供按层目录、连续 UTF-8 原文及精确续读位置；协议 2 采用 12 批／64 KiB 累计成功结果／8 KiB 单页，额度耗尽后消费最后结果并进入回答。同一逻辑工具跨 Run 只显示一项，暂停不再重复显示失败。产品、测试、README 和源记录与审查版本一致；沿用源 72 项客户端测试、Renderer 类型检查及 Vite 构建，Main 全量检查的既有 97 项诊断无新增。原 3 份外来文档原样保留。未推送、打包或安装；先部署配套 Yuxi API／worker，再更新客户端，真实模型验收另行完成。见[源任务](tasks/20260926-teacher-read-expired-087d82f7.md)和[集成记录](tasks/20260926-merge-teacher-read-ml-616605aa.md)。本条更新新客户端额度，旧条目保留为历史。
+
 - 2026-09-26：从 `287dcd303d3c99665e95eca3345c4ee3270a855f` 无冲突快进合入已独立审查源 `60c20f996e8428d4dfbd5efb92792d3900722af5`。云端咨询最多执行六批本地读取。Yuxi 消费最后一批结果后通过 `tool_choice: none` 请求最终答案；Main 保留第七批保护，并区分 `teacher_read_limit`、`teacher_context_expired` 和 `teacher_protocol_invalid`。真实模型与安装版验收保持独立，失败问题不自动重试。 产品、测试和源记录与审查版本一致，沿用源验证；两仓共 5 份外来文档原样保留。未推送、部署或更新安装版。见[源任务](tasks/20260926-teacher-read-expired-087d82f7.md)和[集成记录](tasks/20260926-merge-teacher-read-ml-616605aa.md)。
 
 - 2026-09-26：合入图标修复源 `a3c02e74649c743c445fb2304bec9e0ac954ad96`，合并提交 `e3d01a1da4c836d0f5c9d9fc42bd9257088a4669`。智能体图标跟随发布定义：Yuxi 将原生 `icon` 固定到发布快照，Works Square 转为公开地址 `icon_url` 下发。Makelore 顶栏、邀请、面板标题、欢迎区和消息行统一读取该字段；缺失或加载失败时回退到既有 `avatar_id`。新话题取当前发布定义，旧话题保持原版本；自定义图标使用正常图像渲染，内置像素头像保持像素样式。 产品与测试保持已审查源字节，复用源验证；7 份跨仓外来文档原样保留且未纳入提交。未推送、部署或更新安装版；发布配套三端后需在运营端同步 Yuxi 配置，新话题使用新版本。见[源任务](tasks/20260926-agent-avatar-ml-3c3686ec.md)及[本次集成](tasks/20260926-merge-agent-avatar-ml-92dc837e.md)。

.project-docs/30-worklog/tasks/20260926-merge-teacher-read-ml-616605aa.md

@@ -12,30 +12,46 @@
 
 ## Scope
 
+- 2026-09-27 follow-up: integrate reviewed source 56cefe84e7b654bcc20f2b8fde7f97336134fec8, including logical activity correction 8a74721 and protocol-2 paged reads, into local main. This resumes the same teacher-read integration; no new product implementation.
+
 - Merge reviewed source 60c20f996e8428d4dfbd5efb92792d3900722af5 into local main and promote the confirmed teacher read-completion contract. No product changes beyond the reviewed source.
 
 ## Intent And Constraints
 
+- Follow-up Concurrent and Planning Gates Passed: official same-task start/status retain exclusive integration ownership and the existing three adopted foreign documents. Loaded own/source records, teacher ADR and canonical context; refreshed 121 peer records with prior unchanged context retained. Historical template scopes remain unknown without a concrete dependency. User-authorized pagination supersedes the old six-batch rule only for protocol 2; no semantic conflict. Merge exact reviewed source, verify product/source-record equality, promote canonical facts and finish documentation; no push, deployment, package, install, cleanup or new reviewer.
+
 - Concurrent and Planning Gates Passed. Official check/start/status establish exclusive integration ownership with Identity above. Loaded entry, own/source records, current teacher positioning/decisions/architecture/domain and evidence/reflection/commitments; inspected peer records and reused unchanged previous context. Historical template scopes/positioning remain unknown with no concrete dependency on this merge.
 - User explicitly approved handing off the previous avatar integration registration through release --force and preserving the known foreign documents through --adopt-existing. All five documents across both repositories stay unchanged and outside commits. Source records stay read-only; no new subagents, push, deployment, installation or deletion.
 - Plan: fast-forward the exact reviewed source, verify ancestry and equality with the reviewed product/test tree, promote runtime facts to canonical memory, pass documentation and whitespace gates, then commit and complete. Reuse source test/review evidence when the product tree is identical.
 
 ## Outcome
 
+- Follow-up merge commit: eb818bc. Local main contains the exact latest reviewed source; only canonical integration notes were added afterward.
+
+- 2026-09-27 follow-up: conflict-free merge of source 56cefe84e7b654bcc20f2b8fde7f97336134fec8. Directory traversal is lazy and breadth-first; files and captured conversations use continuous pages with exact next positions. Protocol 2 uses 12 batches / 64 KiB successful results / 8 KiB per page, and final-answer handling at less than 512 bytes remaining. Logical tool activity no longer doubles across continuation Runs. Teacher ADR, architecture and integrated snapshot now describe accepted behavior; imported source records remain unchanged.
+
 - Fast-forwarded local main to reviewed source 60c20f996e8428d4dfbd5efb92792d3900722af5 without conflicts. Product, tests, public documentation and imported source records match the reviewed source.
 - Promoted the six-batch completion and distinct client error semantics into system-overview and current-state. No conflicting accepted product or billing decision; original read quota/context/version/deadline and student funding remain.
 
 ## Verification
 
+- Follow-up integration checks passed: reviewed product/source-record equality, conflict-free merge, whitespace and official documentation boundary check. The checker recognizes source-owned records after the merge commit; they were imported verbatim, not edited by integration. Previously adopted foreign documents retain their recorded states.
+
+- Follow-up source review_paged_reads: PASS with no remaining material findings after the directory/long-line reader corrections. Reviewer independently reran 72 client cases and two protocol-2 native integration cases. Main product/test/README bytes and source records exactly match reviewed source. Reused 72 focused client tests, Renderer typecheck and Vite build; additional Main typecheck still has 97 pre-existing diagnostics, no added diagnostics. No production or installed-client acceptance claimed.
+
 - Source independent review 20260926-teacher-read-review-b7d3e91a: PASS without material findings; independent reruns covered one six-batch HTTP/PG/Redis/worker/SDK case and six focused client cases.
 - Reused source evidence for identical product/test bytes: Makelore 130 related unit tests plus three corrected malformed-batch cases, typecheck and Vite all-target build passed; existing build warnings remain disclosed.
 - Fast-forward ancestry, exact reviewed product-tree comparison, imported source-record equality, whitespace and official task-aware documentation gates passed. The drift check also confirms all adopted foreign documents retain their original states.
 
 ## Follow-ups
 
+- Latest source result is merged locally; this worktree remains available pending a new bounded post-merge cleanup offer. Existing failed histories are not rewritten or retried. Deploy Yuxi API/worker first, then update the client; no production supplier behavior or billing acceptance inferred.
+
 - Source worktree retained awaiting the separate post-merge cleanup confirmation. Branch and committed result remain preserved; cleanup does not block the completed local merge.
 - Production supplier requests, live billing and installed-client acceptance remain unverified. Deploy the matching Yuxi worker and updated client before acceptance; existing failures are not automatically replayed.
 
 ## Promotion Candidates
 
+- Follow-up pagination/budget and logical-activity proposals accepted under the user's implementation and merge authorization; promoted to teacher ADR, system-overview and current-state. New protocol supersedes the earlier six-batch limit while installed legacy clients retain it. No unresolved semantic conflict.
+
 - Accepted source runtime proposal applied to system-overview/current-state. No new product direction or semantic conflict; no source record modified.