# 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 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`, 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/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.ts`, `src/lib/works-square-token-points.ts`, and `src/components/layout/Sidebar.tsx` | Token Points V2 的 Main-owned 上游代理、安全 DTO 投影、格式化与账号菜单状态 | 管理者可见规范字符串点数与周期；非管理者只见粗粒度可用性。旧 rolling-window usage contract 和 Renderer stale event 已删除。 |
| `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 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,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-07