docs(integration): promote Learning project catalog
This commit is contained in:
@@ -25,9 +25,8 @@
|
||||
| 设计 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 生成工作台 | 无材料：Renderer → Host API；有材料：Renderer → 白名单 IPC → Main strict bounded multipart → Works Square generation | 需求最多 4,000 字；最多 5 个材料、单个 50 MiB、总计 150 MiB；外层对象、id/order/MIME/时间/字节先严格投影，Token 和 multipart 网络请求留在 Main |
|
||||
| Learning 下载与播放 | 课程卡片 / 已安装课程 | Main 账号分区 → 同 Works origin、最多 5 跳的受控下载重定向 → 512 MiB 上限与大小/SHA-256 校验 → 原子本地安装 → account-bound verified loopback production Stage | 资源重定向不携带 Bearer；播放前重验 archive；课程媒体仅允许 MIME/扩展匹配的被动图片、音视频和字体，运行时同时加 nosniff/CSP 并拒绝可执行文档 |
|
||||
| Learning 联网课堂 | 本地 production Stage 的 Agent/ASR/PBL/评分请求 | nonce-protected loopback player → iframe exact source/origin + 单文档 bridge → Renderer 绑定当前已读课程/模块/账号 epoch → allowlisted IPC → Main 验证调用前 active registration → 无副作用权威解析课程/模块 → Works Square | 只有显式课堂读取会注册资源；Agent/runtime 不能靠自身请求注册课程。只允许固定 capability、方法和有界 body/response；二次 iframe 导航永久关闭 bridge，账号变化会丢弃迟到结果并关闭/轮换 player session |
|
||||
| Learning 项目浏览 | Learning 项目列表 / README 详情 | Renderer → typed Host API → Main fixed list/detail routes → Works Square published projects | 保留登录与 `module_access.learning`；Main 严格投影分页项目 DTO，README 禁用原始 HTML，发布时镜像的远程 raster 图片通过固定项目媒体路由和 10 MiB 上限读取 |
|
||||
| Learning 项目下载 | README 详情页“下载项目” | Renderer → Host API → Main 原生保存对话框 → Works archive stream → 临时文件 → 原子重命名 | 最大 512 MiB；最多五跳同 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
|
||||
@@ -41,7 +40,7 @@
|
||||
- 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 Main 本地课程库按当前认证身份派生的不透明 account partition 持有 archive 路径、安装记录和 player registration；Renderer 只接收课程 DTO、classroom 投影和当前账号的 loopback player URL。账号 epoch 变化会使旧异步结果、runtime 事件、player URL/cookie 与注册资源失效。云端进度以课程 aggregate hash 为身份，模块进度附带受控 module id/hash。
|
||||
- Learning 不再维护客户端课程库、生成任务、player registration、进度或 runtime 状态。Main 在一次下载调用内持有当前账号快照、Works 凭据、保存路径和临时文件；账号变化或校验失败会中止并清理临时文件。历史课程数据不会被新逻辑读取，也不会自动删除。
|
||||
- 图生图参考图与视频首帧都先归一为当前 Workspace 的 Asset；从作品选择时复用生成结果 Asset，本地选择时先走既有上传接口，再把唯一 Asset ID 随 Turn 提交。选择或上传成功后关闭选择器。
|
||||
- 本地开发适配器将旧单会话 schema v2 原子迁移为带默认 Conversation 的 schema v3；打包应用不使用该本地适配器作为云端失败回退。
|
||||
- 注销和退出会关闭本地事件流并清除本机 Conversation Session-id 缓存；服务端持久 Session 保留，下一次访问从 Conversation API 重新读取。
|
||||
@@ -64,10 +63,9 @@
|
||||
- 服务端安全投影后的公共 `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 catalog/generation/progress/download、Agent、ASR 与 classroom runtime API；Main 添加当前账号 Bearer Token 并限制路径、DTO、材料、能力与响应大小。
|
||||
- 版本化 OpenMAIC production Stage artifact；CI 按固定 URL/SHA-256 获取，打包前清单校验，运行时只从已验证安装资源或显式开发根加载。
|
||||
- Works Square Learning project list/detail/media/archive API；Main 添加当前账号 Bearer Token，并限制固定路径、DTO、媒体 MIME/大小、归档重定向、字节数和摘要。
|
||||
- 已实现的本机 Robot provisioning capability、固定 portal-open 与 hotspot scan/connect Host API。它们是本地 Main 操作，不读取 Works access token、不调用上游，也不接受任意 URL/SSID/BSSID/interface/profile。
|
||||
|
||||
## Last Updated
|
||||
|
||||
2026-08-19
|
||||
2026-08-20
|
||||
|
||||
@@ -35,9 +35,9 @@
|
||||
| `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 课程、生成、进度、播放与 runtime 的共享 DTO/Renderer facade | 普通云端数据走 Host API；材料、课程包与本地播放器能力走白名单 IPC，Renderer 不持有 Token、归档路径或账号分区键 |
|
||||
| `electron/api/routes/learning.ts` / `electron/services/learning-*.ts` | Main-owned Learning 云端代理、账号分区本地课程库、Agent/ASR/runtime 与播放器服务 | 固定 Works 路径/能力、输入与响应边界；课程包和外部 production Stage artifact 使用大小/摘要/清单校验；player HTTP session 使用账号绑定与 nonce，iframe bridge 使用 exact source/origin 和单文档生命周期 |
|
||||
| `src/pages/Learning/` / `src/components/layout/LearningSidebar.tsx` | 课程广场、生成工作台、模块选择和嵌入式课堂 | 大课保持单课程 aggregate，模块只选择同一已验证包内的 production Stage |
|
||||
| `shared/learning.ts` / `src/lib/learning.ts` | Learning 项目列表、详情、媒体和下载结果的共享 DTO/Renderer facade | 所有访问走固定 Host API；Renderer 不持有 Token、任意上游 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，图片使用受控媒体路径，旧生成/播放器入口不存在 |
|
||||
| `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/上游访问前返回，且只投影稳定安全错误 |
|
||||
@@ -54,7 +54,7 @@
|
||||
- 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 / allowlisted IPC → Main account-bound Learning services → Works Square 或 verified local course/player artifact。Main 从认证身份派生本地不透明分区并以 epoch 拒绝迟到结果；课程 aggregate hash 是云端身份，模块 id/hash 不提升为独立权益主体。
|
||||
- Learning Renderer → typed Host API → Main fixed project routes → Works Square list/detail/media/archive。Main 代理受控图片并持有原生保存与归档校验；Renderer 只获得安全 DTO、图片数据和保存结果。
|
||||
|
||||
## Risky Or Sensitive Areas
|
||||
|
||||
@@ -71,7 +71,7 @@
|
||||
- 多 Conversation 事件处理必须区分对话快照与 Workspace 任务更新；不得用任务时间戳推进 Conversation 流水位，也不得让旧会话的迟到流覆盖当前会话。
|
||||
- Quote 编辑、重报价、确认和项目删除都跨 Renderer/Main/Works Square。异步结果必须核对当前 Workspace + Conversation；删除当前项目时必须先使旧选择和事件流失效，再加载剩余 Workspace。
|
||||
- Prompt Museum 图片和来源 URL 来自服务端数据。服务端必须完成内容授权/署名审核；若未来需要凭据化素材，应新增 Main-owned 媒体代理，不能把对象存储凭据放进 Renderer URL。
|
||||
- Learning 的远端 JSON、错误、下载重定向、课程 ZIP、播放器 artifact 与 iframe runtime 都跨信任边界；必须保持严格 DTO/路径/大小/摘要/账号 epoch/同源重定向/player nonce/exact source+origin/单文档 bridge/能力投影、一次 401 refresh 和固定安全错误，不能把 Renderer/课程内容变成任意 Works 代理。
|
||||
- Learning 的远端 JSON、Markdown、媒体、错误和 ZIP 下载跨信任边界；必须保持严格 DTO、固定项目/媒体路径、可信 raster MIME、媒体/README/归档大小、同源重定向、声明字节数、SHA-256、ZIP 签名、一次 401 refresh 和固定安全错误，不能把 Renderer 或 README 变成任意 Works/网络/文件系统代理。
|
||||
- Gateway 命令的 REST fallback 只处理 WebSocket 发送、断连和 ACK 超时，必须复用 `client_command_id`；业务错误回退会造成重复提交。Quote 任务恢复只更新 Workspace 所有的任务，不能覆盖当前 Conversation。
|
||||
- `closeEventSessions` 只负责本地流和缓存生命周期；远端 Conversation Session 是服务端持久资源。
|
||||
- 单图来源选择器当前仍由精确中文 quick reply 触发，并以 Brief medium 判断图生图或视频首帧用途；扩展更多输入用途前应先把消息协议升级为结构化 action/purpose，避免展示文案与行为继续耦合。
|
||||
@@ -79,4 +79,4 @@
|
||||
|
||||
## Last Updated
|
||||
|
||||
2026-08-17
|
||||
2026-08-20
|
||||
|
||||
@@ -24,8 +24,8 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
|
||||
| AI Design Gateway Routing | Main 云端适配器 ↔ Conversation WebSocket；Main → Host API/SSE → Renderer store | 命令、Run 与设计事件共用双向 WebSocket；Conversation 更新按 Workspace + Conversation 路由，任务更新按 Workspace 归并 |
|
||||
| AI Design Quote & Task Controls | 当前 Conversation Quote 与 Workspace 任务 | 最终 Prompt/generation options 每次修改由服务端重新计价；任务结果在详情中预览并经 Main-owned asset download 保存 |
|
||||
| Prompt Museum | Canvas “获取灵感”页面 → Main Host API → Works Square | 服务端驱动的审核内容、筛选和分页；Renderer 不持有 Works Token 或内置数据集，“使用此 Prompt”只回填输入框 |
|
||||
| Learning Workspace | 课程广场、生成工作台与本地课程播放器 | Renderer 只持有安全课程/进度/任务状态；材料字节、课程归档、播放器产物和云端凭据由 Main 持有 |
|
||||
| Learning Main Boundary | Host API + bounded IPC services → Works Square / account-partitioned verified local course library | 课程 API、生成、下载、Agent、ASR 与固定 runtime capability 由 Main 执行；课程包和 production Stage artifact 在使用前校验，账号切换使旧本地库、player registration 与迟到结果失效 |
|
||||
| Learning Project Catalog | 服务端分页项目卡片、README 详情与用户选择的 ZIP 下载 | Renderer 只持有安全项目 DTO 和 Markdown；不提供生成、进度、本地课程库或播放器 |
|
||||
| Learning Main Boundary | 固定 Host API → Works Square project list/detail/media/archive | Main 持有 Works Bearer、媒体代理、原生保存路径、受控重定向、临时文件、大小/SHA-256/ZIP 签名校验与原子落盘；Renderer 不获得任意 URL 或本地路径 |
|
||||
|
||||
| Robot Workspace | Account-scoped agent configuration, device activation/binding, assignment, and credential-recovery UI | Renderer receives only safe Works Square projections. Configuration choices come from the USER-scoped safe catalog; unavailable current values remain editable without exposing provider credentials or configuration internals. |
|
||||
| AI Hardware Main Route | Fixed `/api/works/ai-hardware` Host API to Works Square proxy | Main owns Bearer auth, stable operation IDs, bounded retry, ETag/If-Match, request/response limits, error redaction, and the fixed no-store configuration-catalog proxy. Versioned responses accept only canonical strong or weak numeric ETags that equal the DTO revision; mutations always emit strong `If-Match`. It never forwards Renderer authorization headers. |
|
||||
@@ -41,7 +41,7 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
|
||||
- Product UI language is Chinese-only. Unsupported system or persisted language values normalize to `zh`; removed locale files are not runtime fallbacks.
|
||||
- Packaged Canvas remains cloud-only with no local fallback. `pnpm run dev` now uses the cloud adapter; the local Workspace adapter requires the explicit development command and remains unpackaged-only.
|
||||
- Prompt Museum is a read-only curated inspiration surface, not a user-content community. Main owns Works authentication and forwards only the bounded list/detail routes; the client never bundles museum content or automatically submits a selected Prompt.
|
||||
- Learning uses a Main-owned cloud and local-package boundary. Renderer does not receive Works credentials, archive paths, provider/model configuration, or an arbitrary network proxy. Main derives an opaque account partition from the authenticated identity, bounds same-origin archive redirects and package extraction, and serves registered course assets only from an account-bound loopback player with exact-origin and nonce checks; classroom runtime is limited to explicit capabilities and aggregate-course identity.
|
||||
- Learning uses a Main-owned read-only project-catalog boundary. Renderer does not receive Works credentials, object-storage identifiers, arbitrary download URLs, temporary/final paths, or an arbitrary network proxy. README raw HTML is disabled; publish-time mirrored raster images use fixed project-media paths. Main validates media and streams a selected project ZIP through bounded same-origin redirects, declared size, SHA-256, ZIP signature, and atomic rename before returning only `saved` or `cancelled`.
|
||||
- AI hardware network access is Main-owned. Renderer cannot hold Works Square or Xiaozhi credentials and cannot select arbitrary upstream paths or headers.
|
||||
- Robot model, language, and voice choices are dynamically projected from the Xiaozhi USER catalog through Works Square and Electron Main; the catalog is bounded, account-scoped, and `private, no-store` at each public hop.
|
||||
- One local account maps to one server-side Xiaozhi account binding. Agents and devices are resources beneath that account binding, not separate Xiaozhi users.
|
||||
@@ -77,8 +77,8 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
|
||||
|
||||
## Related Decisions
|
||||
|
||||
- 当前长期边界记录于 README、ADR-001 至 ADR-004、集成任务 `20260807-integrate-login-client-a4f8`、源任务 `20260810-static-release-only-a91c`、`20260812-client-built-release-makelore-7e5b`、`20260812-design-image-to-image-client-c91e` 及本次 Integration Gate；后续如改变唯一入口、凭据所有权、构建执行边界、Conversation 状态归属、Robot 配网/绑定安全边界或重新引入客户端部署协调器，应新增 ADR。
|
||||
- 当前长期边界记录于 README、ADR-001 至 ADR-005、集成任务 `20260807-integrate-login-client-a4f8`、源任务 `20260810-static-release-only-a91c`、`20260812-client-built-release-makelore-7e5b`、`20260812-design-image-to-image-client-c91e` 及本次 Integration Gate；后续如改变唯一入口、凭据所有权、构建执行边界、Conversation 状态归属、Learning 项目分发边界、Robot 配网/绑定安全边界或重新引入客户端部署协调器，应新增 ADR。
|
||||
|
||||
## Last Updated
|
||||
|
||||
2026-08-19
|
||||
2026-08-20
|
||||
|
||||
Reference in New Issue
Block a user