makelore/.project-docs/20-architecture/module-map.md

Module Map

Source Layout

Path	Responsibility	Owner Notes
electron/coding-teacher/**, electron/api/routes/coding-teacher.ts, shared/coding-teacher.ts, and src/pages/Chat/Teacher*.tsx	Main-owned 云配置、来源上下文、本机话题、模型调用、Host API/SSE、独立右侧答疑与运营试聊	无 Pi worker 或工具；固定发布版本，账号/项目/来源会话隔离。见 teacher ADR。
electron/coding-projects/project-config.ts, src/pages/Chat/CodingProjectConversations.tsx, and src/components/layout/Sidebar.tsx	内部默认 Agent 与项目下会话导航	旧绑定保留；首次发送或显式新建创建会话，打开项目不创建。
electron/coding-plugins/manifest.ts, release-descriptor.ts, signature-verifier.ts, and trusted-keys.ts	Closed Plugin package/descriptor parsing, fixed code-owned resource roots, compatibility checks, canonical archive validation, and Ed25519 trust	Data Service plus exact Game Resource, Game Audio and Project Scaffold roots are code-owned. Other schema-2 packages still pass descriptor/signature/archive validation; downloadable P0 Skill assets remain text/image-only. Hosted Web Search is not a current Plugin root.
electron/coding-plugins/account-plugin-cache.ts, marketplace-client.ts, and package-store.ts	Main-owned Account Library cache, authenticated server client, and atomic immutable device installation store	Account acquisition and device installation are separate. Package bytes switch atomically only after descriptor, signature, archive, client-range, and provenance checks; failed updates preserve the prior current release.
shared/coding-plugins.ts, electron/coding-plugins/effective-resolver.ts, registry.ts, project-service.ts, and electron/coding-runtime/pi/**	Effective official Plugin projection, selected-model tools, Device Package resources, and frozen parent logical-thread runtime snapshot	The shared project-wide predicate covers makelore.data-service, makelore.game-resource, makelore.game-audio, and makelore.project-scaffold: after their existing delivery/acquisition requirement and project enablement, all parent Agents receive their Skills/tools without assignment. Trusted Marketplace artifacts that require assignment and immutable local Device Package generations retain their distinct authorities. Child workers remain empty; active threads retain frozen resources until settlement/disposal.
electron/coding-runtime/pi/model-tools/** and shared/model-tools.ts	Closed selected-model tool registry and provider-specific Web Search request shaping	The frozen selected model capability controls whether makelore_web_search exists. The tool uses that model/provider/credential and normal model billing; no Hosted Plugin adapter, Admission, Plugin Charge, or browser fallback exists.
electron/coding-packages/**, electron/api/routes/device-packages.ts, shared/device-packages.ts, and src/stores/device-packages.ts	Main-owned conversation install preview/confirmation/commit, immutable local package generations, safe Renderer projection, and parent-worker refresh	Sources are npm, Git, absolute local Plugin directories, or loose SKILL.md. Lifecycle scripts are disabled; executable extensions and non-empty Skill scripts/ run with desktop-user authority after disclosure and explicit confirmation. Every generation projects all explicitly installed and currently enabled Skills/extensions; Device Packages never join Account Library, Marketplace Package Store, Release, Channel, or Admission state.
electron/coding-plugins/adapters/game-resource.ts, electron/services/game-resource-client.ts, and electron/services/game-resource-delivery.ts	Provider-neutral makelore.game-resource adapter, Main-owned Works Square transport, and durable local delivery coordinator	An eligible frozen parent submits one confirmed generation. Main polls internally, persists delivery state under userData, downloads every terminal output, and writes it to the frozen original project. A delivery retry resumes download/save only; Renderer/Pi never receive Provider URLs, credentials, balances, raw responses, Provider job IDs, or filesystem authority.
electron/coding-plugins/adapters/game-audio.ts, electron/services/game-audio-client.ts, game-audio-delivery.ts, and src/pages/Chat/GameAudioFiles.tsx	Project-wide music/preview/sound tools, durable single-submit delivery, and click-only local audio preview	Main persists intent before POST, uses by-operation lookup after uncertain submission and resumes only the existing execution. Frozen account/project and shared write leases govern all-output materialization; receipt-owned content reaches native audio controls only on a user click, never as a Provider URL or model-message audio payload.
electron/api/routes/plugin-marketplace.ts, src/stores/{plugin-marketplace,device-packages,coding-plugins}.ts, src/pages/Plugins/, and src/pages/ProjectConfiguration/index.tsx	Existing Main/store authorities plus the unified Renderer projection embedded in Project Configuration	/project-config/plugins is the canonical same-page sheet state. /plugins and legacy Plugin routes only replace-redirect while preserving deterministic filters. official:, local:, and retained: identities stay separate, source failures are isolated, and no Account token, filesystem path, Admission, package bytes, signed URL, or visible install-source picker enters Renderer.
src/components/works/ProjectPublishAction.tsx	可发布项目的一键提交、云构建轮询与用户可理解状态	只通过 Renderer API 提交非敏感元数据；绑定告警不终止轮询
shared/project-config.ts, electron/coding-projects/{project-config,project-service}.ts, and src/components/layout/Sidebar.tsx	规范 ProjectType、Main-owned UUID 与目录式最小项目创建	普通新建只要求目录，内部默认 interactive_ai_app，Main 自动生成 UUID；有效旧配置仅缺 projectId 时串行修复。既有 custom 和历史类型仍兼容，initialized 不再是导航 gate
resources/coding-plugins/project-scaffold/ and tests/project-scaffold/	官方 bundled Scaffold Plugin、固定六文件模板、确定性 Node 脚本、发布要求参考与回归测试	通过既有 Pi bash write lease 和 MAKELORE_NODE_EXECUTABLE 显式运行；脚本信任来自固定客户端资源，而非下载 artifact；不覆盖、不安装依赖、不联网，也不复制 build/upload/review 实现
src/lib/works-square.ts	Renderer 侧 Works Square Host API 契约与安全错误映射	不接触 Token、ZIP、本地绝对路径或自动部署状态
electron/api/routes/works-billing.ts, shared/works-billing.ts, src/lib/works-billing.ts, src/components/account/PointWallet.tsx and src/components/layout/Sidebar.tsx	永久词元点数的 Main-owned 认证与公开 DTO、个人余额、充值/订单恢复、流水及账号菜单	本人余额精确可见；另一付款方用 shared_available 表示可用性，不以 family_shared 或旧会员权限推测。显式充值意图复用请求身份，服务端确认后到账；旧订阅/重置卡入口及 DTO 已移除。
electron/api/routes/works.ts	Works Host API、Renderer capability 门禁、上游安全投影	发布凭据、打包、上传与本地绑定均在 Main 内完成
electron/services/project-release-builder.ts	Main-owned 安全快照、本地 npm/Vite 构建、source+built 双归档与 v1 contract	固定 npm 11.6.2；项目 Vite 由 lockfile 决定；Vite config/plugins 以桌面用户权限执行
electron/services/publish-runtime.ts	安装包内 npm 闭包定位与 Electron Node 执行	不回退全局 npm/PATH；缺失或版本不符 fail closed
electron/services/static-release-server.ts	用内存 built snapshot 建立一次性 loopback origin	预检和最终上传归档必须来自相同文件字节；总是清理临时服务
electron/agent-browser/module.ts, electron/api/routes/agent-browser.ts, src/lib/agent-browser.ts, and src/pages/Chat/AgentBrowserPanel.tsx	项目级共享开发浏览器、可见 viewport 协调、Console/Network 诊断与 built artifact 临时预检	用户和 parent Agent 共享同一 sandboxed 页面；Main 校验当前项目、generation、bounds 与 CDP method。诊断按 owner 引用计数，关闭/切换/隐藏/休眠会释放 view 与 debugger；发布预检仍只是 UX fail-fast，不生成可信 receipt。
electron/agent-browser/electron-adapter.ts	Electron WebContents/CDP 设备指标、事件与临时 partition 适配	probe 不挂载 UI，并在结束后销毁视图、清理隔离存储
electron/services/project-packager.ts	受控项目扫描、静态 ZIP 生成和敏感/历史控制文件排除	只允许可发布 ProjectType，不提供 Compose 或手工 ZIP 路径
electron/services/works-submission-binding.ts	submission binding v2 持久化与旧 schema 迁移	旧中间态终止为 legacy_retired；文件名暂作安装兼容
electron/api/works-play-url.ts	公共播放 URL 的共享安全校验	公共 play_url 必须同源 HTTPS 且精确匹配 App 路径
src/pages/Chat/CodingChatPanel.tsx / CodingConversationTimeline.tsx / CodingComposer.tsx	Agent/Conversation 选择、Snapshot-first 时间线、prompt/steer/follow-up、交互、压缩、分支与附件 UI	Composer 不等待 worker 准备；lifecycle:sleep 关闭旧 SSE，视图挂载、项目上下文变化、页面可见或窗口 focus 静默刷新已选 Snapshot；时间线初始渲染最近 120 个节点并按 100 个节点向前扩展、保持滚动锚点；所有异步结果按 project/Agent/Conversation 所有权隔离，Renderer 不导入 Pi wire 类型
src/stores/coding-conversations.ts / coding-workspace.ts	per-Conversation Snapshot/Patch、乐观提交、gap/foreground recovery 与项目级元数据	generation/seq 严格递增；只恢复目标 Conversation，SSE 重连与前台刷新不重放 mutation；隐藏红点只响应新的 pending interaction 或 run terminal transition，不响应普通助手/工具过程
shared/coding-conversation-*.ts / coding-project-contracts.ts	Main/Renderer 共用的产品中立 Conversation、project tool、subagent 与 reducer 合同	这是唯一公共实现；Pi 事件、RPC 与 Provider 形状保持 Main-private
electron/api/coding-composition.ts / electron/api/routes/coding-*.ts	唯一 Main-owned Coding composition 与 /api/coding/* Host API	管理 project/Agent/Conversation、SSE、附件、文件、命令、交互和安全诊断；mutation 返回 202 acceptance 且按 request id 去重
electron/coding-projects/	.makelore/project.json 与 .makelore/conversations.json schema-v2 项目/Agent/Conversation 数据、原子持久化与项目文件能力	不读取或迁移 .niancode / .opencode 项目元数据；legacy 内容保持 inert 且不删除
electron/coding-runtime/conversation-service.ts / conversation-title.ts	产品级 Conversation orchestration、首条用户消息命名、模型/思考强度、fork/archive/recover 与运行时门禁	unresolved Conversation 先验证并持久化模型再首次 prepare；Main 生命周期订阅和 hydration 触发一次元数据命名，手动标题优先；归档保留 runtime，仅阻止新发送与 fork；元数据失效事件与 sequenced runtime Patch 分离
src/pages/Chat/CodingConversationSidebar.tsx / CodingConversationRenameDialog.tsx	每个 Agent 的最近/归档列表、独立行菜单和标题栏共用重命名对话框	菜单操作不选择或准备目标；最后一条会话归档后保留空态；归档会话以恢复入口替代 Composer，恢复沿用同一 Conversation
electron/coding-runtime/pi/{agent-server-process,worker-pool,worker-process,rpc-client,session-registry,event-projector,session-projector}.ts / resources/pi-agent-server.mjs	一个长驻父 Agent Server 内的 per-Conversation 逻辑 Runtime/Session/channel、严格 LF JSONL RPC、generation recovery 与 Snapshot/Patch 投影	首个 extension 必须是生成的 Makelore bridge，所有后续显式 extension 作为 Pi additionalExtensionPaths 加载且不启用 ambient discovery；Session hydration 保留完整 active-branch 可见历史并把 compaction summary 留在 Main-private 模型上下文；正式包按 staged pi-runtime 的 manifest/root 解析并校验 Pi 包入口；top-level logical-turn cap 4、warm idle LRU 8；线程级替换只使目标 generation 失效，Server 退出使所有旧 channel 失效并在下次恢复时只重启一个 Server
electron/coding-runtime/pi/{provider-config,provider-refresh,provider-failure,resource-loader}.ts / electron/api/routes/ai-proxy.ts	Main-owned Provider catalog、secret/env 投影、资源 revision、一次凭据刷新与上游错误分类	secret 不进入 argv/catalog/Renderer；确定性的 Works user-context 缺失使缓存凭据过期并 fail fast，不自动重放 mutation；精确 Token Point exhaustion 被窄化为安全、不可重试、可持久恢复的产品错误，不透传原始上游正文
electron/coding-runtime/pi/{extension-host,subagent,write-lease}.ts / electron/main/background-lifecycle.ts	必需 Makelore extension、显式安装且启用的 Device Package extensions、交互、子 Agent、同项目写租约与后台运行租约	parent generation 加载完整 Main-selected extension 集；child 并发 4、单次最多 8、禁止递归；active/uncertain run 不因页面隐藏或确认超时被回收，所有 stop/replacement 必须有原因
electron/main/updater.ts	目标 feed 解析、electron-updater 生命周期与原始诊断	缺少稳定 manifest 保持错误；事件/Promise 重复失败按检查实例去重
src/components/settings/UpdateSettings.tsx	更新状态、重试与用户可读错误展示	只显示一条简洁中文提示；技术诊断统一回退到本地化通用文案
shared/image-workspace.ts	AI Design V2 Workspace、Direction、Living Form、immutable Quote、Task、Asset 与事件共享契约	Current Specification 是唯一语义权威；Task/Asset 属于独立 Workspace resource projection；public activity 是固定、operation-scoped presentation contract
electron/api/routes/image-workspace.ts	AI 绘画 Host API 与本地事件流投影	Renderer 只通过该路由访问 Main-owned workspace adapter
electron/image-workspace/works-square-workspace.ts	Works Square V2 adapter、stable command/operation IDs 与 Direction event mapping	unknown transport result 保留精确命令；Main 持有 token、ticket、WebSocket、retry classification、safe errors，并把闭集 progress stage 归一为固定 youth-safe copy
src/stores/image-workspace.ts	Current Workspace/Direction/Living Form、local drafts、pending operations、operation activity 与 Workspace resources	revision conflict 刷新 canonical state；activity/delta/terminal event 按 Workspace、Direction 和 operation identity 收敛；event order/Task progress 不成为 Specification authority
src/pages/ImageCanvas/{index,DesignConversationPane,DesignProductionPanel,DesignPlanHistory,DesignHistoryRail,DesignWorksRail,YouthCreationCard}.tsx	左侧 Workspace 项目导航、中央 conversation/active 制作方案与 operation-scoped AI activity、右侧全高历史作品栏、immutable Quote confirmation	active 方案留在时间线；桌面端已提交 Tasks 与 Assets 进入右侧历史栏，紧凑窗口仍在时间线内展示。固定活动附着于对应 user bubble 且不成为对话、制作方案或模型思考过程；最终 Prompt、reference binding 与直接参数编辑继续通过同一 V2 reducer，确认只提交 Quote ID
src/pages/ImageCanvas/reference-tokens.ts and src/pages/ImageCanvas/youth-form-projection.ts	@图片N alias、缺失 binding 检测与青少年可读方案投影	Prompt 是 reference 用途的唯一可见表达；binding row 只管理真实 Asset/token identity。缺失 token 对应图片时提供定点上传并阻止 Quote，新增/删除/替换保持稳定 reference ID 与连续 alias
src/pages/ImageCanvas/DesignHistoryRail.tsx	当前 Workspace 的全高右侧历史作品栏	桌面为 320–340 px 右 rail，按时间展示 Tasks 与生成 Assets；紧凑布局将同一历史保留在中央时间线
src/pages/ImageCanvas/DesignWorksRail.tsx	紧凑布局的 Workspace 选择、创建和删除	仅作为左侧项目 Sheet 使用；无“获取灵感”入口，不创建嵌套 Conversation
shared/image-prompt-museum.ts and electron/api/routes/image-prompt-museum.ts	Dormant Museum DTO 与 Main-owned 列表/详情/auth/media 安全边界	当前 App 不挂载 Museum Renderer 页面；历史路由回到 Canvas。仅保留固定 GET/媒体校验兼容，不代表可见模块
src/pages/AiHardware/index.tsx	Robot 管理、现有六位 Binding，以及已实现的 default-on 引导式热点配网状态机	只编排非敏感步骤；不接收 Wi-Fi 密码，不把 bound 展示为在线证明
src/lib/ai-hardware.ts	Renderer 侧 Robot Host API 类型、安全错误映射和稳定 Binding/hotspot facade	读取 Main-owned capability，调用固定 portal-open，并只传递短效 hotspot candidate ID；不添加任意 URL、SSID 或 Renderer IPC
electron/api/routes/ai-hardware.ts	Main-owned Robot 云端代理，以及本地 capability/portal/hotspot actions	默认开启、精确环境值 0 回滚；所有本地操作必须在 Works token/上游访问前返回，且只投影稳定安全错误
electron/robot-hotspot/index.ts	Robot hotspot 深模块：候选过滤/去重/TTL、操作互斥、超时和精确 SSID 核验	只接受 Adapter 输出与不透明 candidate ID；Renderer 不能选择任意 SSID
electron/robot-hotspot/windows.ts	Windows 原生 WLAN 扫描、临时开放网络连接和当前 SSID 查询	懒加载 wlanapi.dll；不使用 netsh、不保存 profile、不主动断开
electron/robot-hotspot/macos.ts	macOS CoreLocation 授权与 worker-owned CoreWLAN 扫描/关联/核验	Objective-C 对象不跨线程；取消/超时终止 worker，旧终止屏障阻止迟到权限/native continuation
electron/robot-hotspot/adapter.ts	平台 Adapter 的最小内部契约与稳定错误分类	平台细节不进入 Host/Renderer 公共 DTO

Dependency Direction

• Renderer UI → Renderer API contract → Main Host routes → Main services → Works Square；Renderer 不反向读取 Main 凭据、文件系统或归档。
• Project Configuration 插件 card → canonical /project-config/plugins same-page sheet → unified Renderer stores → bounded Main Marketplace and Device Package routes. /plugins and legacy URLs replace-redirect into deterministic filters and do not create a second lifecycle.
• Hosted Game Resource parent tool → frozen Registry adapter → Main delivery coordinator → GameResourceClient → fixed Works Square game-resource routes → durable local receipt → frozen project output directory. Stable logical operation identity survives response loss and Main restart; ambiguous submission remains reviewable and is never converted into an automatic fresh mutation. Main polls internally and acquires the shared project write lease only while materializing terminal outputs; resuming delivery never submits or charges again.
• AI 编程 Renderer product Snapshot/commands → typed /api/coding/* Host API → Main Coding composition → target CodingConversationRuntime → shared Agent Server 内的目标 Pi 逻辑线程；Pi Provider 请求再经 Main AI proxy 访问模型上游。Renderer 不持有 Pi wire、凭据或本地 runtime URL。
• 普通项目创建只收集目录并使用内部 interactive_ai_app 默认与 Main-owned UUID；既有 Project Configuration 继续管理 Agent/Skill/知识/插件。用户可选地显式调用 Scaffold Skill 生成固定起步文件；Main release builder 生成 source/built/contract，服务端独立重算和校验决定发布安全。本地 ProjectType 或 Skill 准备度结论都不是授权结论。
• Built artifact preflight 检查最终上传的同字节快照，但客户端可被绕过且不产生可信 receipt；服务端仍是合同、摘要和不可变 Release 安全权威。
• Robot Renderer → typed AI hardware API → Main Host route → Robot Hotspot Module → Windows/macOS Adapter。云端 Binding 仍由 Main 代理；热点选择/连接移入页面，但家庭 Wi-Fi 凭据输入仍只留在固件 Portal，系统 Wi-Fi 保留为兜底。
• 历史 /image-prompts → App replace-redirect → /image-canvas。Museum Main API/DTO 保持 dormant；当前 Renderer 没有可达的 Museum 数据流或 pending-Prompt 导航。

Risky Or Sensitive Areas

• electron/api/routes/works.ts 同时承担发布 capability、上游安全投影和错误脱敏，变更时必须验证未在拒绝前读取凭据或项目文件。
• platform_hosted mutation eligibility, explicit confirmation, stable identity, Admission and receipt status form one authority chain. submission_unknown cannot create a new request, and a billing pending_review receipt cannot be inferred from transport ambiguity. Production remains fail closed until the official Marketplace signing key and server-side activation gates are ready.
• project-release-builder.ts 执行受信本地项目的 Vite config/plugins，拥有桌面用户权限；必须保持路径、环境、时间、输出、进程树和临时目录限制，不得包装为 sandbox。
• electron/agent-browser/module.ts 的预检必须继续拒绝外域访问、隔离临时 partition 并清理所有 view/listener；不能因本地通过而跳过服务端逐字节校验。生产 opaque-origin 行为不由该 loopback 检查覆盖。
• works-cloud-deploy.json 是兼容文件名；不得因名称重新引入自动部署协调语义。
• runtime_url 是一个客户端版本的迁移回退；删除前必须确认服务端和存量数据稳定提供 play_url。
• Pi RPC confirmation timeout is an uncertainty boundary, not permission to release run/process/background ownership. Late success/failure/exit/abort must converge monotonically and exactly once; no accepted or uncertain mutation may be replayed automatically.
• Pi manual compaction in locked 0.84.2 does not emit agent_settled; correlated compact RPC success or an authoritative compaction failure must terminalize the compact operation without prematurely settling an ordinary prompt.
• Pi compaction is a model-context boundary, not a visible-history deletion boundary. Full active-branch hydration must keep compaction summaries private, and Renderer windowing must preserve the user's scroll anchor while prepending older nodes.
• Provider quota classification must remain exact and redacting: unrelated 403/429 failures cannot be reinterpreted as Token Point exhaustion, while reopened recognized failures must preserve only the stable product code and safe Chinese message.
• Shared parent logical threads do not consume one process lease each. Independent child Agents remain capped at 4 against the FIFO process budget of 8; stop failure must release child leases in finally.
• Provider/resource revisions apply before the next prompt for idle logical threads and after agent_settled for active runs. Same-account model changes may use set_model; cross-account changes rebuild only the target Conversation thread so old credentials never enter the new credential store.
• electron/main/updater.ts 的稳定源错误归一化必须保持窄化：只识别 Works Square 对应 manifest 的 404，不得吞掉其他 feed/网络/签名错误；Renderer 的脱敏边界不能取代 Main 原始日志。
• Design V2 事件处理必须区分 Direction projection 与 Workspace Task/Asset projection；不得用 transport sequence 或 Task progress 推进 Specification revision。
• 输入、Quote request、confirmation 和项目切换跨 Renderer/Main/Works Square。异步结果必须核对 Workspace、Direction、revision 与 operation identity；unknown write 复用原 identity，不能生成新业务意图。
• Dormant Prompt Museum API/media 代码仍必须保持 Main-owned Bearer、固定路径、可信 raster MIME、10 MiB 上限和错误脱敏；如未来重新启用产品面，需新的明确产品决策与端到端授权/署名审核。
• Design command replay requires the original stable command and semantic operation IDs; business rejection never authorizes a retry with a fresh identity. Resource reconciliation cannot overwrite the Living Form.
• Canvas cleanup only closes the local stream/buffers. The server-owned Direction Session and semantic history remain durable.
• Image/video references use typed Asset binding and Specification medium; display text is never an action protocol.
• Guided Hotspot Binding 已由产品决策默认开启，并通过 native dependency 执行未经认证的热点扫描/连接。未完成指定固件镜像核对、六位码发行契约、签名 macOS x64/arm64 worker/ASAR/Koffi 验证、Windows 真机和完整 Electron/Robot smoke 前不得宣称完整兼容；现场异常使用精确环境值 0 回滚。

Last Updated

2026-09-22