79 lines
17 KiB
Markdown
79 lines
17 KiB
Markdown
# Data Flow
|
||
|
||
## Primary Flows
|
||
|
||
| Flow | Source | Destination | Notes |
|
||
|---|---|---|---|
|
||
| Marketplace catalog and Account Library | Signed-in Renderer intent | bounded Host API → Main Marketplace client/cache → Works Square catalog, Library, resolve, Admission, and download APIs | Main binds requests to the current Account and response generation. Free acquisition changes only Account Library; it does not install, enable a project, assign an Agent Skill, or authorize runtime execution. |
|
||
| Marketplace device installation | Account Library entry and explicit channel | Main resolve/Admission/download → descriptor/signature/archive/client compatibility verification → immutable Package Store index switch | Stable and explicit Beta remain distinct even when they resolve to the same immutable Release. Failed install/update retains the previous current release; explicit uninstall waits only for protecting worker/account references and completes after the final worker exits. |
|
||
| Effective Plugin worker snapshot | Installed trusted package + project selection + Agent assignments + current server policy | effective resolver → Registry/resource loader/Extension Host/tool catalog → parent Pi worker | One frozen snapshot supplies Skills, tools, package roots, and runtime authorization. Disable, account/project switch, logout, Renderer crash, Main shutdown, or worker generation change invalidates future actions without mutating persisted unknown assignments; child workers receive no Plugin projection. |
|
||
| 桌面认证生命周期 | Renderer 登录、刷新与注销请求 | Host API → Main Works Session → Works Square `/api/auth/{login,mobile-login,refresh,logout}` → one-feel auth | Main 加密持有并先持久化轮换 token；客户端不携带 OAuth client secret；连续 7 天未使用才清除会话，终止性 `400`/`401` fail closed |
|
||
| 用户模块入口策略 | 会话恢复 / 登录 / 刷新 | Electron Main → Works `/api/auth/me` → 四布尔安全投影 → Renderer auth store → 卡片/路由/provider gate | 缺失对象或字段默认 `true`；`design` 映射 `painting`；终止性 `401` 清理 Main/Renderer 会话；全局 `/settings` 不受 Code gate |
|
||
| 项目创建 | 新建项目对话框 | Host API → Main 项目初始化 | 创建时固定 `ProjectType`；小游戏/小程序原子生成受控模板，自定义只生成项目空间 |
|
||
| 一键提交 | `ProjectPublishAction` | Renderer capability → Host API → Main 本地 npm/Vite build → built snapshot preflight → source+built+contract 上传 | 只对小游戏/小程序开放；首次 create 通过单一 multipart 合同原子提交文字资料与必选 PNG/JPEG/WebP 封面，创建失败或冲突不上传版本；已有 draft/published 只提交版本并沿用云端资料/封面，不做无条件 metadata PATCH |
|
||
| 构建产物预检 | 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 编程 Conversation 创建与准备 | 当前 project / Agent / 本地 Conversation | Renderer 本地创建 → `/api/coding/*` → Main schema-v2 store → target Pi worker/session lazy prepare | Composer 与 worker 准备解耦；首次 Conversation 可立即编辑。未解析模型必须先验证并持久化，再打开首个 worker；旧 OpenCode 会话只备份，不继续运行 |
|
||
| AI 编程 prompt 与流式投影 | 当前 Conversation draft / attachment refs | Renderer mutation → Host `202` acceptance/dedupe → Main target worker → Pi events → Snapshot + `patch-batch` SSE → Renderer reducer | 每个 Conversation 独立 generation/seq；gap 只恢复目标 Conversation。accepted/uncertain mutation 不自动重放，权威 Snapshot 到达前保留相同 optimistic node identity |
|
||
| AI 编程模型与思考强度切换 | 当前 Conversation | Renderer → `/api/coding/conversations/{id}` → Main validate/persist → target runtime | 同账号已解析模型复用 `set_model`；跨账号模型等 active run settled 后只重建目标 worker，旧凭据不会进入新 generation；切换失败不销毁可继续使用的旧 worker |
|
||
| AI 编程上下文压缩 | Renderer compact action / Pi compaction events | correlated compact RPC → target projector → Snapshot/Patch timeline | Pi `0.84.2` 的手动 compact 不发 `agent_settled`；RPC success 或权威 compaction failure 终结 compact 并 exactly-once 释放对应 ownership，不提前结算普通 prompt |
|
||
| AI 编程 Provider 错误 | Pi worker Provider 请求 | selected worker env → Main AI proxy → Works 模型上游 → projector safe error | 确定性的 Works user-context 缺失使缓存 gateway credential 过期、返回非重试认证失败且不重放请求；Renderer 只看到固定 Provider-auth 提示，不能把它解释为 Pi 崩溃 |
|
||
| AI 编程子 Agent | parent `subagent.v1` tool call | explicit extension → authenticated Main bridge → scheduler → ephemeral Pi child | child 并发最多 4、单次最多 8、禁止递归；父子共享总进程预算 8，coding child 与 parent 共用项目 write lease，父 abort/crash/generation 失效必须清理 child 与 permit |
|
||
| 客户端更新检查 | 设置页 | 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 |
|
||
| 设计有限请求生命周期 | Renderer Workspace JSON 调用 / shared Works token refresh | Main deadline → Electron transport → safe-read-only Node fallback → Host API timeout envelope | 包括取凭据、请求头和响应 body 的完整生命周期最多 30 秒；超时 abort transport 并稳定返回 `504 DESIGN_WORKSPACE_REQUEST_TIMEOUT`；透明 fallback 只允许 `GET`/`HEAD`/`OPTIONS`，mutation 不隐式重放 |
|
||
| 设计单图来源选择 | 当前 Workspace 已完成图片 / 本地图片 | 现有 Asset 上传或选择 → `attachmentAssetIds` → 当前 Conversation Turn | 图片 Brief 用作图生图参考图；视频 Brief 用作首帧；只提交一个真实 Workspace Asset ID |
|
||
| 设计任务同步 | 任一 Conversation 的事件流 / Quote REST 对账 | Renderer Workspace 任务列表 | Task 和 Asset 按 Workspace 归并；任务已落库但 Run 失败时恢复可见性，内部对账失败不覆盖新会话错误，切换 Conversation 后仍同步任务但不回写旧会话 |
|
||
| 设计 Quote 编辑与重报价 | 当前 Conversation 的 active Quote | Renderer 修改最终 Prompt/参数 → Main Host API → Works Square Quote update → 当前 Conversation | 服务端返回最新参数与设计点；报价完成前不能确认，确认提交最新原值，客户端不自行计价 |
|
||
| 设计项目删除 | Canvas 侧栏精确项目名确认 | Renderer → Main Host API → Works Square Workspace DELETE | 删除成功后清理当前 Workspace/Conversation/task stream 并选择最近更新的剩余项目；结算与软删除语义由服务端负责 |
|
||
| Prompt Museum 浏览与使用 | Canvas 侧栏“获取灵感” | Renderer → Main Host API → Works Square list/detail；选中 Prompt → 进程内 pending state → 当前 Canvas 输入框 | 只发送白名单筛选/游标；Works Token 留在 Main，Prompt 不自动发送，Museum 不包含客户端静态数据集 |
|
||
| Learning 项目浏览 | Learning 项目列表 / README 详情 | Renderer → typed Host API → Main fixed list/detail routes → Works Square published projects；README 图片节点 → 远程 HTTPS origin | 保留登录与 `module_access.learning`；Main 严格投影分页项目 DTO，README 禁用原始 HTML，仅图片节点可直连无凭据 HTTPS URL；封面和历史媒体仍使用受控媒体读取 |
|
||
| Learning 项目下载 | README 详情页“下载项目” | Renderer → Host API → Main 原生保存对话框 → Works archive stream → 临时文件 → 原子重命名 | 不校验 `Content-Length`、`archiveBytes`、实际流字节数或客户端大小上限；最多五跳同 Works origin 重定向且不向重定向请求携带 Bearer；SHA-256 与 ZIP 签名匹配后才保存，Renderer 只得到 `saved` 或 `cancelled` |
|
||
| Robot 引导式热点配网 V1（已实现、默认开启） | Robot Binding 页面 | 用户选择引导配网 → 进入固件配网模式 → Renderer 经 Host API 请求 Main 扫描 → 用户选择短效候选 → Windows/macOS Adapter 连接并核验当前 SSID → Main 打开固定 Portal → 用户在 Portal 配置 Wi-Fi → 电脑恢复互联网 → 现有六位 Binding | 精确环境值 `0` 或 capability 读取失败回退直接六位码；系统 Wi-Fi 保留兜底，Makelore 不收集 Wi-Fi 密码、不修改固件，热点发现/`bound` 都不等于可信身份或 online/ready |
|
||
|
||
## State Ownership
|
||
|
||
- Main 持有刷新凭据、发布 Token、固定 npm runtime、源码/构建归档、临时目录、幂等键和 submission binding v2；Renderer 不持有归档路径、构建 origin 或自动部署状态。
|
||
- 项目内 `.niancode/project.json` 保存 `ProjectType`；Main 在配置写入和目录复用时保持其不可变，并在打包时重新读取校验。
|
||
- Renderer 仅持有短效公开会话状态和提交展示状态。
|
||
- Renderer 可持久化当前账号的四布尔模块入口策略，但不持有原始 Works profile 或 Token。新账号不继承上一账号缓存；网络/暂时上游失败可保留同会话已知策略，终止性 `401` 不得回退到默认开启。
|
||
- 本地构建临时目录、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 列表、生成任务和资产。
|
||
- AI 绘画 Main 持有 Workspace 请求 deadline、底层 transport fallback 和共享 Works token refresh flight。共同等待者必须在同一有限期限内 settle，refresh flight 结束后必须释放，后续刷新可重新发起；底层 mutation transport failure 不得自动产生第二次上游请求。
|
||
- Prompt Museum pending Prompt 是 Renderer 进程内一次性导航状态；Canvas 消费后立即清除，不进入 Workspace/Conversation 直到用户主动发送。
|
||
- Learning 不再维护客户端课程库、生成任务、player registration、进度或 runtime 状态。Main 在一次下载调用内持有当前账号快照、Works 凭据、保存路径和临时文件；账号变化或校验失败会中止并清理临时文件。历史课程数据不会被新逻辑读取，也不会自动删除。
|
||
- 图生图参考图与视频首帧都先归一为当前 Workspace 的 Asset；从作品选择时复用生成结果 Asset，本地选择时先走既有上传接口，再把唯一 Asset ID 随 Turn 提交。选择或上传成功后关闭选择器。
|
||
- 本地开发适配器将旧单会话 schema v2 原子迁移为带默认 Conversation 的 schema v3；打包应用不使用该本地适配器作为云端失败回退。
|
||
- 注销和退出会关闭本地事件流并清除本机 Conversation Session-id 缓存；服务端持久 Session 保留，下一次访问从 Conversation API 重新读取。
|
||
- project、Agent、Conversation schema v2 与每条 Conversation 的 opaque Pi session binding 由 Main 原子持久化。旧 v1 先做时间戳备份再迁移；旧 OpenCode Session 不进入新 runtime，也不删除无关 `.opencode` 内容。
|
||
- Renderer Store 只拥有产品中立 Snapshot、Patch、optimistic request 与 project-scoped metadata。每条 Conversation 的 generation/seq 独立；stale generation 丢弃，gap/reconnect 只为目标 Conversation 取 Snapshot 并重放严格连续的缓冲 tail，不重放 mutation。
|
||
- Main 为每条 active/warm Conversation 持有一个 persistent Pi worker/session、Provider/resource revision 和 selected-account secret env。运行中 stale revision 保留本 run snapshot，settled 后重建；其他 Conversation 不受影响。
|
||
- top-level worker 并发上限 4、warm idle LRU 上限 4、child 并发上限 4，parent/child 共用 FIFO process budget 8。同项目 coding mutation 共用 write lease；read-only child 可旁路写锁。
|
||
- prompt/compact 的 RPC confirmation timeout 只进入 uncertain，不能释放 run permit、process ownership 或 Main background lease。迟到 success/failure/exit/abort 必须单调且 exactly-once 收敛；隐藏页面超过 grace 也不得停止 active/uncertain run。
|
||
- AI 编程压缩状态属于目标 Conversation Snapshot。Pi `0.84.2` 手动 compact 的 correlated RPC success 可代替缺失的 `agent_settled` 终结 compact；普通 prompt 仍只由权威 terminal/settled 结束。
|
||
- Main Host AI proxy 持有凭据刷新和错误分类。确定性 Works user-context 缺失必须失效缓存 credential 并 fail fast；真实认证、endpoint/proxy/rate-limit、Provider variation、真实并发与跨 worker 凭据隔离仍是用户明确接受但未验证的风险。
|
||
- Main AppUpdater 持有 feed、原始异常、下载和安装状态；设置页只消费状态投影。一次 electron-updater `error` 事件覆盖的并发检查不会在 Renderer 重复发错，但独立的后续检查仍有自己的报告生命周期。
|
||
- Robot V1 引导状态只在 Renderer 当前进程内保存，不持久化 Wi-Fi 凭据、activation code 或 Binding operation ID。相同进程内的模糊 Binding 重试复用 operation ID；无效码或重启后必须取得新码并使用新 operation ID。
|
||
- Robot Hotspot Module 只在 Main 内保存最近一次扫描的短效、不透明候选快照。新的扫描、clear、60 秒过期或进程重启使旧 candidate ID 失效；Renderer 关闭/重开向导以 generation 防止旧扫描/连接结果回写。
|
||
|
||
## External Interfaces
|
||
|
||
- Works Square 项目创建、版本上传、构建状态与 Release 状态 API。
|
||
- Works Square `/api/auth/me` 模块权限 API；Electron Main 持有 Bearer 并只向 Renderer 投影 `programming`/`design`/`learning`/`robot` 对应的四个布尔值。
|
||
- 本机 Host API 的发布路由；发布路由要求 Renderer capability。
|
||
- 本机 `/api/coding/*` project/Agent/Conversation、Snapshot/patch-batch SSE、prompt/compact/fork/recover、attachment/file/interaction/diagnostics 路由，以及 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 传输回退。
|
||
- Works Square Prompt Museum list/detail API；Main 添加当前账号 Bearer Token，Renderer 只使用 Host API 投影。
|
||
- Works Square Learning project list/detail/media/archive API；Main 添加当前账号 Bearer Token，并限制固定路径、DTO、封面/历史媒体 MIME/大小、归档重定向、摘要和 ZIP 签名；归档大小字段只作展示，不参与下载门禁。README 中经服务端校验的无凭据 HTTPS 图片由 Renderer 图片节点直接请求。
|
||
- 已实现的本机 Robot provisioning capability、固定 portal-open 与 hotspot scan/connect Host API。它们是本地 Main 操作，不读取 Works access token、不调用上游，也不接受任意 URL/SSID/BSSID/interface/profile。
|
||
|
||
## Last Updated
|
||
|
||
2026-08-26
|