merge: 合入下发智能体图标修复

.project-docs/30-worklog/tasks/20260926-agent-avatar-ml-3c3686ec.md

@@ -0,0 +1,49 @@
+# Task: Diagnose distributed agent avatar propagation
+
+## Identity
+
+- Task ID: 20260926-agent-avatar-ml-3c3686ec
+- Mode: Feature
+- Branch: codex/20260926-agent-avatar-ml-3c3686ec-agent-avatar-ml
+- Worktree: D:\Datas\OthersProjects\.codex-worktrees\makelore\20260926-agent-avatar-ml-3c3686ec
+- Base commit: 9147b509c71f3ea765e5aaa8f542fd0a74bd4653
+- Owner: codex
+- Status: Ready for Integration
+
+## Scope
+
+- Diagnose and repair the missing Yuxi icon across publication, distribution and client rendering. User authorized implementation after the source diagnosis.
+
+## Intent And Constraints
+
+- Preserve immutable publication/replay and old-topic semantics, student billing, source storage ownership and existing local avatar fallback.
+- No live configuration, deployment, automatic synchronization, main-branch merge or modification of peer worktrees.
+- Concurrent ownership and Planning Gate passed in the same isolated task worktree. Same-base project memory and peer task scopes were retained from diagnosis; no new peers at resumption. Historical placeholder peer scopes remain unknown with no identified semantic conflict.
+- Plan completed: froze the icon in Yuxi, resolved and preserved it in Works Square, rendered it consistently in Makelore, then verified each boundary. The one user-authorized fresh read-only reviewer approved the complete change with no blocking findings.
+
+## Outcome
+
+- Added optional icon_url to the distributed TeacherDefinition. TeacherAvatar handles the configured image and falls back to avatar_id when absent or when loading fails; new image URLs can be attempted after an earlier failure.
+- Topbar entries, legacy/history companion entry, invitation speaker, panel header, welcome and assistant message rows use TeacherAvatar. Custom images use normal rendering; bundled pixel art keeps pixelated rendering.
+- Updated README and added actual UI/browser regressions.
+
+## Verification
+
+- RED: both new tests failed with built-in avatar src instead of the expected cloud URL before implementation.
+- GREEN: pnpm exec vitest run tests/unit/teacher-companion.test.tsx tests/unit/coding-teacher-ui.test.tsx: 56 passed.
+- pnpm exec tsc --noEmit and focused ESLint passed. pnpm run build:vite passed for renderer, Main, preload and utility worker; existing Browserslist/chunk warnings remain.
+- Real Edge Playwright distributed-icons case passed, including actual image decoding, independent 404 fallback, normal image rendering and the invitation speaker. Screenshot inspected in test-results; test route supplies deterministic image bytes, not production OSS.
+- No installed Electron package or live production visual acceptance.
+
+## Follow-ups
+
+- Independent review passed. One non-blocking evidence gap remains: no combined test updates catalog metadata while an old topic is already open; existing separate data-flow tests and source inspection support the pinned-topic behavior.
+- Task documentation drift checks passed across all three repositories; commit the scoped result for integration.
+- Deploy compatible Yuxi, Works Square and Makelore versions, then use Operations sync to publish the existing agent's icon. Older topics keep their original published definitions.
+
+## Promotion Candidates
+
+- Target: .project-docs/20-architecture/system-overview.md and integrated current-state when useful.
+- Proposal: record the versioned icon contract: native Yuxi icon becomes a frozen teacher snapshot field, WS resolves the public URL, client renders it with local fallback.
+- Evidence: production diff plus regression results above. Future impact: visual identity follows the same publication boundary as other agent metadata.
+- Semantic conflicts: none identified. Human confirmation: implementation authorized; canonical promotion and main-branch merge remain a separate integration task.