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

Module Map

Source Layout

Path	Responsibility	Owner Notes
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/Web Search roots are code-owned. Other schema-2 skill_only/platform_hosted packages remain signed Marketplace artifacts and fail closed without the official public key.
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.
electron/coding-plugins/effective-resolver.ts, registry.ts, project-service.ts, and electron/coding-runtime/pi/**	One effective Plugin projection and frozen parent logical-thread runtime snapshot	Project enablement and Agent Skill assignment are preserved independently. Trusted installed artifacts or exact acquired official bundled definitions may enter a policy-admitted parent logical thread; child workers remain empty and active threads retain frozen resources until disposal.
electron/coding-plugins/adapters/game-resource.ts and electron/services/game-resource-client.ts	Provider-neutral makelore.game-resource hosted tool adapter and Main-owned Works Square transport	Tools materialize only from an eligible frozen platform_hosted parent snapshot. Metered mutations require explicit confirmation and stable logical operation identity; Renderer/Pi never receive Provider URLs, credentials, balances, raw responses, or Provider job IDs.
electron/api/routes/plugin-marketplace.ts, src/stores/plugin-marketplace.ts, src/pages/PluginMarketplace/, src/pages/MyPlugins/, and src/pages/ProjectPlugins/	Bounded Main routes and Renderer projections for catalog, Library, device, and project actions	Renderer receives no Account token, filesystem path, Admission, package bytes, or signed download URL. Catalog/Library/device/project generations prevent stale A/B or cross-action results from replacing current state.
src/components/works/ProjectPublishAction.tsx	可发布项目的一键提交、云构建轮询与用户可理解状态	只通过 Renderer API 提交非敏感元数据；绑定告警不终止轮询
src/lib/works-square.ts	Renderer 侧 Works Square Host API 契约与安全错误映射	不接触 Token、ZIP、本地绝对路径或自动部署状态
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	built artifact 的桌面/移动临时 WebContents/CDP 预检	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 准备；所有异步结果按 project/Agent/Conversation 所有权隔离，Renderer 不导入 Pi wire 类型
src/stores/coding-conversations.ts / coding-workspace.ts	per-Conversation Snapshot/Patch、乐观提交、gap recovery 与项目级元数据	generation/seq 严格递增；只恢复目标 Conversation，SSE 重连不重放 mutation
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 orchestration、模型/思考强度、fork/archive/recover 与运行时门禁	unresolved Conversation 先验证并持久化模型再首次 prepare；已解析 Conversation 的模型切换复用 target runtime seam
electron/coding-runtime/pi/{agent-server-process,worker-pool,worker-process,rpc-client,session-registry,event-projector}.ts / resources/pi-agent-server.mjs	一个长驻父 Agent Server 内的 per-Conversation 逻辑 Runtime/Session/channel、严格 LF JSONL RPC、generation recovery 与 Snapshot/Patch 投影	top-level logical-turn cap 4、warm idle LRU 8；线程级替换只使目标 generation 失效，Server 退出使所有旧 channel 失效并在下次恢复时只重启一个 Server
electron/coding-runtime/pi/{provider-config,provider-refresh,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
electron/coding-runtime/pi/{extension-host,subagent,write-lease}.ts / electron/main/background-lifecycle.ts	唯一显式 Makelore extension、交互、子 Agent、同项目写租约与后台运行租约	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
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
src/stores/image-workspace.ts	Current Workspace/Direction/Living Form、local drafts、pending operations 与 Workspace resources	revision conflict 刷新 canonical state；event order/Task progress 不成为 Specification authority
src/pages/ImageCanvas/{index,DesignConversationPane,DesignFormPane,DesignProductionPanel}.tsx	持久双栏 Canvas、conversation、Living Form、immutable Quote confirmation、Tasks 与 Assets	chat/direct edits/decisions/locks/bindings 使用同一 V2 reducer；确认只提交 Quote ID
src/components/layout/ImageWorkspaceSidebar.tsx	Workspace 选择、创建与 Prompt Museum 入口	不再创建或选择嵌套 Conversation
shared/image-prompt-museum.ts	Prompt Museum 列表、分类、详情、署名与分页共享 DTO	客户端不包含内容数据集，只定义服务端字段契约
electron/api/routes/image-prompt-museum.ts	Main-owned Museum 列表/详情代理与 Works 登录态	仅 GET 固定路径和白名单查询；Renderer 不获得 Bearer Token
src/pages/ImagePromptMuseum/index.tsx / src/lib/image-prompt-museum.ts / src/stores/image-prompt-museum.ts	Museum 搜索/筛选/详情与一次性 Prompt 回填	原 Prompt 只带回 Canvas 输入框，不自动发送；页面不接受投稿或互动
shared/learning.ts / src/lib/learning.ts	Learning 项目列表、详情、媒体和下载结果的共享 DTO/Renderer facade	项目 API 访问走固定 Host API；Renderer 不持有 Token、任意归档 URL 或本地路径，README 仅接受无凭据 HTTPS 图片 URL
electron/api/routes/learning.ts / electron/services/learning-project-download.ts	Main-owned Learning 项目代理、封面/历史媒体读取和原生 ZIP 保存	固定 Works 路径、严格 DTO 与媒体 MIME/大小边界、最多五跳同源重定向、SHA-256/ZIP 签名校验和原子重命名；归档不做大小校验
src/pages/Learning/ / src/components/layout/LearningSidebar.tsx	分页项目卡片、README 详情和下载入口	保留登录与 module_access.learning；README 禁用原始 HTML，仅图片节点直连无凭据 HTTPS URL，旧生成/播放器入口不存在
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 凭据、文件系统或归档。
• Hosted Plugin parent tool → frozen Registry adapter → Main GameResourceClient → fixed Works Square game-resource routes. Stable logical operation identity survives response loss and Main restart; ambiguous submission remains reviewable and is never converted into an automatic fresh mutation. Saving a result uses the existing bounded project path and project write lease.
• 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。
• Project configuration 决定产品分流；Main release builder 生成 source/built/contract，服务端独立重算和校验决定发布安全，本地 ProjectType 不是授权结论。
• 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 保留为兜底。
• Prompt Museum Renderer → typed Host API facade → Main fixed list/detail route → Works Square。Museum 只把用户明确选择的 Prompt 原文暂存到进程内 Store 并导航回当前 Canvas；不会直接触发 Agent 命令或生成任务。
• Learning Renderer → typed Host API → Main fixed project routes → Works Square list/detail/media/archive。Main 代理受控图片并持有原生保存与归档校验；Renderer 只获得安全 DTO、图片数据和保存结果。

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.
• 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，不能生成新业务意图。
• Prompt Museum 图片和来源 URL 来自服务端数据。服务端必须完成内容授权/署名审核；若未来需要凭据化素材，应新增 Main-owned 媒体代理，不能把对象存储凭据放进 Renderer URL。
• Learning 的远端 JSON、Markdown、媒体、错误和 ZIP 下载跨信任边界；必须保持严格 DTO、固定项目/封面/历史媒体路径、可信 raster MIME、媒体/README 大小、同源重定向、SHA-256、ZIP 签名、一次 401 refresh 和固定安全错误。ZIP 下载明确不校验 Content-Length、archiveBytes、实际流字节数或客户端大小上限。README 仅允许图片节点直连经服务端校验的无凭据 HTTPS URL，不能扩展为任意 Works 下载或文件系统代理。
• 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-08-31