7.1 KiB
7.1 KiB
Data Flow
Primary Flows
| Flow | Source | Destination | Notes |
|---|---|---|---|
| 登录续期 | Renderer 活动信号 | Main Works Session | 连续 7 天未使用才清除会话 |
| 项目创建 | 新建项目对话框 | Host API → Main 项目初始化 | 创建时固定 ProjectType；小游戏/小程序原子生成受控模板，自定义只生成项目空间 |
| 一键提交 | ProjectPublishAction |
Renderer capability → Host API → Main 本地 npm/Vite build → built snapshot preflight → source+built+contract 上传 | 只对小游戏/小程序开放；Main 自动版本、幂等重试和脱敏，Renderer 轮询服务端校验/固化状态 |
| 构建产物预检 | Main-owned built snapshot | 一次性 loopback origin → fresh Electron WebContents/CDP（桌面、移动） | 检查错误、白屏和外域；不调用 Playwright，检查与上传归档相同字节，但不产生可信 receipt |
| 提交绑定 | 云端成功上传响应 | Main → submission binding v2 | 只持久化成功的 app/version/review/hash；落盘失败返回固定告警但不反转提交 |
| 运营发布 | Works Square 审核与交付 | 公共 play_url |
客户端只消费服务端发布结果；真实合同校验 → OSS/CDN 生产链仍待整链验收 |
| 可信发布门禁 | source+built+artifact contract | 服务端逐字节重算/合同校验 → 不可变 Release 固化 → 人工审核 | 服务端不运行项目 Vite；仍是不可绕过权威，未来 runtime 强门禁需可信 verifier |
| AI 编程首次发送 | ChatPanel 当前 Agent | Renderer Store → Host API → Main → OpenCode session / prompt | 新建 session 已知为空时直接提交 prompt，不在关键路径等待空历史；历史未知或普通历史会话仍按默认路径加载消息 |
| AI 编程上下文压缩 | OpenCode compaction Part / session.compacted / /compact |
Renderer Store → per-session transcript state → Chat mixed timeline | 手动请求先创建 immutable UI event；native identity 负责归并与回放去重；完成只更新压缩项，真实 idle 才结束 run 和释放队列 |
| AI 编程模型代理错误 | OpenCode provider 请求 | Main Host AI proxy → Works 模型上游 | 配额耗尽保持独立终止态；只有明确的分组上游饱和才投影为 OpenCode 终止状态，通用限速仍保留 429 |
| 客户端更新检查 | 设置页 | Renderer update store → IPC → Main AppUpdater → 目标 feed | Main 记录并重抛原始错误；Renderer 只显示去重、脱敏的单条提示，稳定源缺包不伪装为最新版 |
| 设计会话创建/切换 | AI 绘画页面或侧栏 | Renderer API → Main → Workspace Conversation API | 新会话属于现有 Workspace；读取独立消息、Brief、Quote 和 turnRevision |
| 设计消息与确认 | 当前 Conversation | Main ↔ 持久 Agent Gateway Session WebSocket → Conversation 快照 | command.submit、Run 与设计事件共用连接；传输失败才以同一幂等 ID 回退 REST；结构化业务错误不重试且未知文本由 Main 脱敏；请求和流式结果同时绑定 Workspace + Conversation |
| 设计单图来源选择 | 当前 Workspace 已完成图片 / 本地图片 | 现有 Asset 上传或选择 → attachmentAssetIds → 当前 Conversation Turn |
图片 Brief 用作图生图参考图；视频 Brief 用作首帧；只提交一个真实 Workspace Asset ID |
| 设计任务同步 | 任一 Conversation 的事件流 / Quote REST 对账 | Renderer Workspace 任务列表 | Task 和 Asset 按 Workspace 归并；任务已落库但 Run 失败时恢复可见性，内部对账失败不覆盖新会话错误，切换 Conversation 后仍同步任务但不回写旧会话 |
State Ownership
- Main 持有刷新凭据、发布 Token、固定 npm runtime、源码/构建归档、临时目录、幂等键和 submission binding v2；Renderer 不持有归档路径、构建 origin 或自动部署状态。
- 项目内
.niancode/project.json保存ProjectType；Main 在配置写入和目录复用时保持其不可变，并在打包时重新读取校验。 - Renderer 仅持有短效公开会话状态和提交展示状态。
- 本地构建临时目录、HTTP origin 和预检 WebContents/partition 只属于一次调用；预检读取与
built_archive相同的内存字节，但结果不写为可信上传 receipt，也不覆盖生产 opaque-origin。 - 旧 schema v1
submitted记录迁移并保留；旧armed、waiting_for_package、waiting_for_login、uploading、failed归一为legacy_retired，不再启动 watcher 或上传任务。 - AI 绘画 Conversation 持有消息、Brief、Quote、
turnRevision和服务端 Session 绑定；Workspace 持有 Conversation 列表、生成任务和资产。 - 图生图参考图与视频首帧都先归一为当前 Workspace 的 Asset；从作品选择时复用生成结果 Asset，本地选择时先走既有上传接口，再把唯一 Asset ID 随 Turn 提交。选择或上传成功后关闭选择器。
- 本地开发适配器将旧单会话 schema v2 原子迁移为带默认 Conversation 的 schema v3；打包应用不使用该本地适配器作为云端失败回退。
- 注销和退出会关闭本地事件流并清除本机 Conversation Session-id 缓存；服务端持久 Session 保留，下一次访问从 Conversation API 重新读取。
- AI 编程 Store 的
sessionMessagesBySessionIdown-key 是加载状态契约：键缺失表示历史未知，存在且值为[]表示已知为空。只有后者可使用不读取历史的快速选择；普通历史会话选择继续刷新消息。 - AI 编程压缩状态由 transcript 中的
compactionsById/compactionOrder单一持有。运行中 hydration 保留 manual pending identity 并用 native Part 合并；completed 不得回退为 running。session.compacted不是 run idle，不能据此释放 queued prompt；失败、中止或 runtime generation 变化只清理对应未完成事件。 - Main Host AI proxy 可为固定 OpenCode 重试契约做窄化的内部状态投影：配额耗尽投影为
402，明确上游分组饱和的429投影为终止400，其他429原样保留；升级 OpenCode 时必须重新验证该契约。 - Main AppUpdater 持有 feed、原始异常、下载和安装状态；设置页只消费状态投影。一次 electron-updater
error事件覆盖的并发检查不会在 Renderer 重复发错，但独立的后续检查仍有自己的报告生命周期。
External Interfaces
- Works Square 项目创建、版本上传、构建状态与 Release 状态 API。
- 本机 Host API 的发布路由；发布路由要求 Renderer capability。
- 本机 Host API 的 OpenCode session、history 与 prompt 路由，以及 Main-owned AI 模型代理。
- Main-owned electron-updater IPC 与 Works Square 平台/架构稳定 feed；正式安装产物发布不由 Renderer 控制。
- 服务端安全投影后的公共
play_url；只接受同源 HTTPS、精确 App 路径和可信版本状态。 - Works Square Workspace/Conversation API、每个 Conversation 的持久 Agent Gateway Session、单次 WebSocket ticket、双向命令/事件帧与幂等 REST 传输回退。
Last Updated
2026-08-15