docs: integrate Learning removal

This commit is contained in:
inman
2026-09-04 12:15:32 +08:00
parent bd0873f348
commit 5f87a42d59
11 changed files with 174 additions and 58 deletions

View File

@@ -12,7 +12,7 @@
| Effective Plugin worker snapshot | Installed trusted package or acquired official bundled definition + 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. |
| Hosted Game Resource operation | Eligible parent `makelore.game-resource` tool call plus explicit confirmation | frozen Plugin adapter → capability Registry → Main `GameResourceClient` → fixed Works Square game-resource route → provider-neutral receipt/result | Server policy owns pricing, payer, Admission and receipt state. Stable logical operation identity survives response loss/Main restart; `submission_unknown` is not replayed as a fresh request. Result saving uses a bounded project-relative path and the existing project write lease. |
| 桌面认证生命周期 | 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 |
| 用户模块入口策略 | 会话恢复 / 登录 / 刷新 | 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 |
@@ -35,8 +35,6 @@
| Design Task and Asset sync | Direction event stream / Workspace resource events / explicit refresh | Renderer Task/Asset projections | Task/Asset events独立于 Living Form;transport order 和 progress 不改写 Specification,也不授权新生成操作 |
| 设计项目删除 | Canvas 侧栏精确项目名确认 | Renderer → Main Host API → Works Square Workspace DELETE | 删除成功后清理当前 Workspace/Direction/resources 并选择最近更新的剩余项目;结算与软删除语义由服务端负责 |
| 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
@@ -44,13 +42,14 @@
- Main 持有刷新凭据、发布 Token、固定 npm runtime、源码/构建归档、临时目录、幂等键和 submission binding v2;Renderer 不持有归档路径、构建 origin 或自动部署状态。
- 项目内 `.makelore/project.json` 是 `ProjectType`、Agent 与 Coding 项目配置的唯一权威;Main 在配置写入和目录复用时保持 `ProjectType` 不可变,并在打包时重新读取校验。
- Renderer 仅持有短效公开会话状态和提交展示状态。
- Renderer 可持久化当前账号的四布尔模块入口策略,但不持有原始 Works profile 或 Token。新账号不继承上一账号缓存;网络/暂时上游失败可保留同会话已知策略,终止性 `401` 不得回退到默认开启。
- 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 Design Current Specification 与 current Direction 是语义权威;conversation timeline 只保存交互历史,immutable Quote 绑定精确 Specification revision,Task/Asset 属于 Workspace resource projection。
- AI 绘画 Main 持有 Workspace 请求 deadline、底层 transport fallback 和共享 Works token refresh flight。共同等待者必须在同一有限期限内 settle,refresh flight 结束后必须释放,后续刷新可重新发起;底层 mutation transport failure 不得自动产生第二次上游请求。
- Prompt Museum pending Prompt 是 Renderer 进程内一次性导航状态;Canvas 消费后立即清除,不进入 Workspace/Specification,直到用户主动提交 Design input。
- Learning 不再维护客户端课程库、生成任务、player registration、进度或 runtime 状态。Main 在一次下载调用内持有当前账号快照、Works 凭据、保存路径和临时文件;账号变化或校验失败会中止并清理临时文件。历史课程数据不会被新逻辑读取,也不会自动删除。
- Retired Learning data is outside the active client state model. Historical downloaded
course data is not read, migrated, or automatically deleted.
- 图生图参考图与视频首帧都先归一为当前 Workspace Asset,再通过 typed binding 写入 Specification;本地路径不会进入 canonical contract。
- Development 与 packaged Canvas 都使用 Main-owned Works Square V2 adapter。V1 DTO/local semantic adapter 与 local/cloud mode switches 已删除,不存在失败回退。
- 注销和退出关闭本地 event stream、清除 drafts/pending state 和凭据;服务端 current Direction Session 与 semantic history 保持持久化。
@@ -68,14 +67,13 @@
## External Interfaces
- Works Square 项目创建、版本上传、构建状态与 Release 状态 API。
- Works Square `/api/auth/me` 模块权限 API;Electron Main 持有 Bearer 并只向 Renderer 投影 `programming`/`design`/`learning`/`robot` 对应的四个布尔值。
- Works Square `/api/auth/me` 模块权限 API;Electron Main 持有 Bearer 并只向 Renderer 投影 `programming`/`design`/`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 Design V2 Workspace/Direction/Living Form API、持久 Agent Gateway Session、Direction event stream,以及 `design.input.apply`、`design.quote.request`、`design.generation.confirm` stable-operation contract。
- 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

View File

@@ -42,9 +42,6 @@
| `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 项目列表、详情、媒体和下载结果的共享 DTO/Renderer facade | 项目 API 访问走固定 Host API;Renderer 不持有 Token、任意归档 URL 或本地路径,README 仅接受无凭据 HTTPS 图片 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,仅图片节点直连无凭据 HTTPS URL,旧生成/播放器入口不存在 |
| `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/上游访问前返回,且只投影稳定安全错误 |
@@ -63,7 +60,6 @@
- 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 → Main fixed project routes → Works Square list/detail/media/archive。Main 代理受控图片并持有原生保存与归档校验;Renderer 只获得安全 DTO、图片数据和保存结果。
## Risky Or Sensitive Areas
@@ -83,7 +79,6 @@
- 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,不能生成新业务意图。
- Prompt Museum 图片和来源 URL 来自服务端数据。服务端必须完成内容授权/署名审核;若未来需要凭据化素材,应新增 Main-owned 媒体代理,不能把对象存储凭据放进 Renderer URL。
- Learning 的远端 JSON、Markdown、媒体、错误和 ZIP 下载跨信任边界;必须保持严格 DTO、固定项目/封面/历史媒体路径、可信 raster MIME、媒体/README 大小、同源重定向、SHA-256、ZIP 签名、一次 401 refresh 和固定安全错误。ZIP 下载明确不校验 `Content-Length`、`archiveBytes`、实际流字节数或客户端大小上限。README 仅允许图片节点直连经服务端校验的无凭据 HTTPS URL,不能扩展为任意 Works 下载或文件系统代理。
- 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.

View File

@@ -13,7 +13,7 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
| Project Configuration & Template | 保存不可变 `ProjectType`,原子生成新项目骨架 | 小游戏/小程序生成受控 Vite 模板;自定义保持最小项目空间 |
| Project Release Builder | Main-owned 安全快照、本地 npm/Vite 构建、双归档与 artifact contract | 固定 npm 11.6.2;Vite 由项目 lockfile 锁定;产物与预检使用同一内存字节 |
| Works Session & Remembered Password | Main-owned 登录、刷新、注销、七天真实活动滑动续期与可选密码回填 | 登录、刷新、注销统一经过 Works Square;轮换凭据由 Main 安全持有和持久化。记住密码使用独立的 packaged-only OS 加密记录,不进入 Renderer 持久状态或 Works Square;客户端不携带 OAuth client secret |
| Module Access Policy | Main-owned `/api/auth/me` projection → Renderer auth state → module chooser/router | Renderer 只接收 Code/Canvas/Learning/Robot 四个布尔值;缺失对象或字段默认开启,服务端 `design` 映射客户端 `painting` |
| Module Access Policy | Main-owned `/api/auth/me` projection → Renderer auth state → module chooser/router | Renderer 只接收 Code/Canvas/Robot 三个布尔值;缺失对象或字段默认开启,服务端 `design` 映射客户端 `painting`,额外旧字段被忽略 |
| Submission Binding | 保存云端已接受的精确 app/version/review/hash 绑定 | schema v2 只记录成功提交;旧中间态迁移为 `legacy_retired`,不恢复后台任务 |
| Play URL Projection | 校验服务端公共播放地址 | 只接受同源 HTTPS 和精确 `/apps/{app_id}/`;优先 `play_url`,`runtime_url` 仅一版本回退 |
| Built Artifact Preflight | 在上传前对最终 built snapshot 做桌面/移动 UX fail-fast | Main 使用临时 loopback origin 与 Electron WebContents/CDP;不使用 Playwright、不生成可信证明 |
@@ -31,9 +31,6 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
| AI Design Quote & Task Controls | 精确 Specification revision 编译出的不可变 Quote 与 Workspace Tasks | 客户端只展示 public output summary、warnings、expiry 与 Token Points,并以 Quote ID 确认;Provider Prompt/model/route/storage/billing atoms 不下发 |
| AI Design Assets | Workspace 已完成作品或本地上传的真实 Asset | Asset 通过 typed binding 写入 Specification;生成结果经 Main-owned asset download 保存 |
| Prompt Museum | Canvas “获取灵感”页面 → Main Host API → Works Square | 服务端驱动的审核内容、筛选和分页;Renderer 不持有 Works Token 或内置数据集,“使用此 Prompt”只回填输入框 |
| 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 签名校验与原子落盘;归档下载不执行大小校验,README 图片节点可直接加载无凭据 HTTPS URL,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. |
| Robot Hotspot Module | Main-owned bounded scan/connect/verify interface with Windows WLAN and macOS CoreWLAN/CoreLocation adapters | Accepts only short-lived opaque candidates from the latest scan, exposes no BSSID/interface/profile/native diagnostic, and retains the system-Wi-Fi fallback. |
@@ -43,13 +40,15 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
- Renderer 只能通过 Main Host API 发起认证操作。Electron Main 是 access/refresh token 的唯一客户端所有者;登录、刷新、注销统一经过 Works Square 固定路由,客户端不得直连 one-feel/custom 身份服务,也不得保存 confidential OAuth client secret。
- 可选的记住密码记录属于 Electron Main 的独立本机边界,只能在正式安装包且 OS 凭据加密可用时落盘;Renderer 不得持久化账号密码,Works Square 不得接收记住标志或新增密码持久化。
- Code、Canvas、Learning 与 Robot 是四个已启用顶层产品模块;Robot 仍是唯一硬件产品模块,不存在单独 Hardware 卡片。
- 每个登录用户可由 Works `module_access` 关闭任意顶层模块入口。Main 只投影四个布尔值;被关闭卡片置灰不可点,根/深层/别名路由在 `MainLayout` 和模块初始化前拦截。Code provider 必须等待 auth policy hydration,而全局 `/settings` 不属于 Code policy guard。
- Code、Canvas 与 Robot 是三个已启用顶层产品模块;Robot 仍是唯一硬件产品模块,不存在单独 Hardware 卡片。
- 每个登录用户可由 Works `module_access` 关闭任意顶层模块入口。Main 只投影三个布尔值;被关闭卡片置灰不可点,根/深层/别名路由在 `MainLayout` 和模块初始化前拦截。Code provider 必须等待 auth policy hydration,而全局 `/settings` 不属于 Code policy guard。
- 模块入口策略是用户交互与客户端初始化边界,不是服务端 API 授权。终止性 `/api/auth/me` `401` 必须清理 Main 和 Renderer 会话;各模块 API 仍须独立强制认证与授权。
- Product UI language is Chinese-only. Unsupported system or persisted language values normalize to `zh`; removed locale files are not runtime fallbacks.
- Canvas is cloud-only in development and packaged builds. The removed local Workspace adapter and V1 DTOs are not fallback paths.
- 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 read-only project-catalog boundary. Renderer does not receive Works credentials, object-storage identifiers, arbitrary archive URLs, temporary/final paths, or an arbitrary network proxy. README raw HTML is disabled; Markdown image nodes alone may load validated credential-free HTTPS URLs directly, including SVG and other formats Electron supports. Main continues to validate covers/historical media and streams a selected project ZIP through bounded same-origin redirects, SHA-256, ZIP signature, and atomic rename before returning only `saved` or `cancelled`; it ignores archive size metadata and applies no client download-size ceiling.
- Learning is retired. No Learning route, Renderer surface, Main Host API, download service,
shared DTO, packaging asset, or fallback remains. Historical downloaded course data is
not read, migrated, or automatically deleted.
- 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.
@@ -97,7 +96,7 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
## Related Decisions
- 当前长期边界记录于 README、ADR-002 至 ADR-007(ADR-001 已由 ADR-007 supersede)及各 Integration Gate;后续如改变唯一入口、凭据所有权、构建执行边界、Living Form/Specification 状态归属、Pi 单 runtime/worker/lease 边界、Learning/Marketplace/Web Search 分发边界、Robot 配网边界或重新引入客户端部署协调器,应新增 ADR。
- 当前长期边界记录于 README、ADR-002 至 ADR-007(ADR-001 与 ADR-005 已 supersede)及各 Integration Gate;后续如改变唯一入口、凭据所有权、构建执行边界、Living Form/Specification 状态归属、Pi 单 runtime/worker/lease 边界、Marketplace/Web Search 分发边界、Robot 配网边界、重新引入 Learning 或重新引入客户端部署协调器,应新增 ADR。
## Last Updated