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

Module Map

Source Layout

Path	Responsibility	Owner Notes
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	公共播放与 Owner preview URL 的共享安全校验	公共 play_url 必须同源 HTTPS 且精确匹配 App 路径
electron/api/routes/device-preview.ts	精确提交版本的待审/已发布真机预览解析	待审使用短时 Release preview，已发布优先 play_url
src/pages/Chat/OpencodeChatPanel.tsx	AI 编程 Agent 选择、首次 session 创建与 prompt 提交流程	新 session 仅在消息缓存 own-key 已知时使用不读取历史的快速选择
src/stores/opencode.ts	OpenCode runtime、session、消息缓存与提交状态	sessionMessagesBySessionId 键缺失表示未知，存在空数组表示已知为空；普通选择默认刷新历史
electron/api/routes/ai-proxy.ts	Main-owned 模型代理、凭据边界与上游响应投影	仅对明确上游分组饱和做终止态兼容投影，通用限速保持 429
shared/opencode-error-details.ts	OpenCode 上游饱和错误的窄化共享分类	不以通用 rate_limit_exceeded 单独判定饱和
shared/image-workspace.ts	AI 绘画 Workspace、Conversation、Task、Asset 与事件共享契约	Conversation 状态与 Workspace 任务归属必须分离
electron/api/routes/image-workspace.ts	AI 绘画 Host API 与本地事件流投影	Renderer 只通过该路由访问 Main-owned workspace adapter
electron/image-workspace/works-square-workspace.ts	Works Square 多 Conversation 云端适配器与 Gateway 事件映射	使用服务端持久 Session；本地清理不 DELETE 远端 Session
electron/image-workspace/local-workspace.ts	未打包开发模式的本地 Workspace 适配器和 v2→v3 迁移	仅开发使用，不得成为打包回退
src/stores/image-workspace.ts	当前 Workspace/Conversation、项目任务及流式更新状态	异步结果按 Workspace + Conversation generation/revision 防护
src/pages/ImageCanvas/index.tsx	Conversation 对话、Quote 确认、统一任务列表、新会话入口与单图来源选择器	图片 Brief 选择/上传图生图参考图；视频 Brief 绑定首帧；均提交一个 Workspace Asset ID
src/components/layout/ImageWorkspaceSidebar.tsx	Workspace 与近期 Conversation 切换/创建	切换会话不清空项目级任务

Dependency Direction

• Renderer UI → Renderer API contract → Main Host routes → Main services → Works Square；Renderer 不反向读取 Main 凭据、文件系统或归档。
• AI 编程 Renderer → Host API → Main OpenCode routes/runtime；OpenCode provider 请求再经 Main AI proxy 访问模型上游，Renderer 不直接持有上游凭据或本地 runtime URL。
• Project configuration 决定产品分流；Main release builder 生成 source/built/contract，服务端独立重算和校验决定发布安全，本地 ProjectType 不是授权结论。
• Built artifact preflight 检查最终上传的同字节快照，但客户端可被绕过且不产生可信 receipt；服务端仍是合同、摘要和不可变 Release 安全权威。

Risky Or Sensitive Areas

• electron/api/routes/works.ts 同时承担发布 capability、上游安全投影和错误脱敏，变更时必须验证未在拒绝前读取凭据或项目文件。
• 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。
• ai-proxy.ts 的上游饱和状态投影依赖当前固定 OpenCode 的重试语义和窄化错误文案；升级 runtime 或调整上游错误格式时必须复核，不能把所有 429 统一终止。
• 多 Conversation 事件处理必须区分对话快照与 Workspace 任务更新；不得用任务时间戳推进 Conversation 流水位，也不得让旧会话的迟到流覆盖当前会话。
• closeEventSessions 只负责本地流和缓存生命周期；远端 Conversation Session 是服务端持久资源。
• 单图来源选择器当前仍由精确中文 quick reply 触发，并以 Brief medium 判断图生图或视频首帧用途；扩展更多输入用途前应先把消息协议升级为结构化 action/purpose，避免展示文案与行为继续耦合。

Last Updated

2026-08-13