文档：集成图生图客户端契约
This commit is contained in:
@@ -13,12 +13,13 @@ This file is the integrated default-branch snapshot. Feature tasks record progre
|
||||
- `926056a`：Makelore 内置 Electron WebContents/CDP 发布前本地预览检查。
|
||||
- `5b44864`：Main-owned 本地 npm/Vite 构建、同字节 Electron 双视口预检、source+built 双归档与 artifact contract 上传。
|
||||
- `08da976` / `0ee5254`：AI 编程首次发送已知空 session 快速路径与明确上游饱和终止态投影。
|
||||
- `809364e` / `88281b8`：AI 绘画单参考图图生图选择/上传交互及其在最新客户端主线上的集成提交。
|
||||
|
||||
## Current Focus
|
||||
|
||||
客户端面向非专业用户提供“创建小游戏或小程序 → 项目配置中一键提交 → Main 本地 npm/Vite 构建 → Electron 双视口预检最终产物 → 上传 source+built 双归档与 contract → 运营审核”的唯一创建者链路。Main 对安全源码快照运行安装包内固定 npm 11.6.2 的 `npm ci --ignore-scripts`，再显式调用项目 `package-lock.json` 锁定的 Vite；Vite config/plugins 以当前桌面用户权限执行，因此只适用于用户信任的本地项目，不是 sandbox。预检由 Main 以临时 loopback origin 和 Electron WebContents/CDP 检查与最终 `built_archive` 相同的内存文件字节，覆盖桌面/移动视口、运行错误、白屏和外域访问；不使用 Playwright。该检查仍可由非官方客户端绕过，不产生可信 receipt，也不复刻生产 opaque-origin。服务端不再替客户端运行项目 Vite，而是把源码、构建归档和 contract 视为不可信输入，逐字节重算与校验并固化不可变 Release；人工审核仍不可绕过。自定义和缺少类型字段的旧项目不提供该入口。已发布作品优先使用安全投影后的 `play_url`，`runtime_url` 仅保留一个客户端版本的兼容回退。
|
||||
|
||||
AI 绘画的一个 Workspace 可包含多条 Conversation。消息、Brief、Quote 和 `turnRevision` 随 Conversation 隔离；生成任务和资产保持 Workspace 级共享。每条 Conversation 使用服务端持久 Agent Gateway Session，切换会话只重连对应事件流。
|
||||
AI 绘画的一个 Workspace 可包含多条 Conversation。消息、Brief、Quote 和 `turnRevision` 随 Conversation 隔离；生成任务和资产保持 Workspace 级共享。图片 Brief 支持文生图，以及从当前项目已完成作品或本地上传中选择一张参考图继续生成；视频复用同一选择器绑定首帧。两条路径都通过现有 Workspace Asset 契约提交一个真实 Asset ID。每条 Conversation 使用服务端持久 Agent Gateway Session，切换会话只重连对应事件流。
|
||||
|
||||
AI 编程首次发送在新建 OpenCode session 已知为空时不再等待冗余历史读取，prompt 可直接进入 Host API；普通历史会话仍刷新消息。Main AI proxy 只把明确的上游分组饱和投影为当前 OpenCode 的终止状态，配额耗尽保持独立终止态，通用限速继续保留 `429`。
|
||||
|
||||
@@ -32,6 +33,7 @@ AI 编程首次发送在新建 OpenCode session 已知为空时不再等待冗
|
||||
- 2026-08-12：一键提交前复用当前项目的内置浏览器 loopback preview，以 fresh 临时 Electron WebContents/CDP 执行桌面/移动 UX 预检；服务端仍执行唯一受控构建、不可变 Release 安全门禁和人工审核。
|
||||
- 2026-08-12：发布架构反转为 Main-owned 本地构建；固定 npm 11.6.2 按项目 lockfile 安装并执行项目 Vite，Electron 预检最终上传同字节产物，再上传 source+built 双归档和严格 contract。服务端仅校验并固化不可信字节，不再承担项目 Vite 构建。
|
||||
- 2026-08-12：AI 编程新 session 的首条 prompt 不再被已知空历史读取阻塞；明确上游分组饱和会快速终止，通用 `429` 仍保持原有限速语义。
|
||||
- 2026-08-13：AI 绘画把原视频首帧选择器泛化为单图来源选择器；图片 Brief 可选择项目作品或上传本地图作为图生图参考图，视频及未决 medium 保持历史首帧行为，成功提交后关闭弹窗。
|
||||
|
||||
## In Progress
|
||||
|
||||
@@ -62,7 +64,8 @@ AI 编程首次发送在新建 OpenCode session 已知为空时不再等待冗
|
||||
- 服务端持久 Conversation Session 不由客户端在注销或退出时删除；Main 只关闭本地流、清除本机缓存并撤销本地凭据。
|
||||
- 客户端对最终构建字节的 loopback 检查没有可信 receipt，且不复刻生产 opaque-origin；服务端必须独立重算 source/built/contract、校验不可变 Release，人工审核仍不可绕过。如未来需要不可绕过的 runtime gate，必须引入可信 verifier 并绑定精确构建产物。
|
||||
- AI proxy 的明确饱和 `429 → 400` 是与当前 OpenCode 重试契约匹配的内部投影；升级 OpenCode 或上游饱和错误文案变化时必须复核。不得把通用 `429` 或仅含 `rate_limit_exceeded` 的响应误分类为终止饱和。
|
||||
- AI 绘画单图选择器仍精确匹配 quick reply `从作品列表选择图片`，用途再从当前 Brief medium 推断；本地化或协议文案变化可能破坏入口。扩展更多素材输入前应升级为结构化 action/purpose。
|
||||
|
||||
## Last Updated
|
||||
|
||||
2026-08-12
|
||||
2026-08-13
|
||||
|
||||
@@ -39,15 +39,42 @@
|
||||
|
||||
## Outcome
|
||||
|
||||
- Not completed.
|
||||
- Merged reviewed feature commit `809364e` into the current `a03043d` client
|
||||
baseline with merge commit `88281b8`; Git resolved the overlapping
|
||||
`ImageCanvas` and page-test history without source conflicts and preserved the
|
||||
existing first-conversation work.
|
||||
- Promoted the generalized single-image picker, one-Asset attachment boundary,
|
||||
image/video/null-medium behavior, exact-string compatibility risk and
|
||||
production-smoke obligation into the current canonical project memory.
|
||||
- README now describes text-to-image, single-reference image-to-image, project
|
||||
work selection and local upload on top of the latest client product state.
|
||||
|
||||
## Verification
|
||||
|
||||
- Not run.
|
||||
- Source merge preflight used `git merge-tree` against current `main`; only the
|
||||
README paragraph needed an overlapping semantic merge and the final merge
|
||||
completed automatically.
|
||||
- `pnpm install --offline --frozen-lockfile`: passed with the pinned pnpm;
|
||||
dependencies were restored entirely from the local store.
|
||||
- `pnpm exec vitest run tests/unit/image-canvas-page.test.tsx`: `25 passed`.
|
||||
- `pnpm run typecheck`: passed.
|
||||
- `pnpm exec eslint src/pages/ImageCanvas/index.tsx
|
||||
tests/unit/image-canvas-page.test.tsx`: passed.
|
||||
- `pnpm run build:vite`: passed for Renderer, Main and Preload; emitted only the
|
||||
repository's existing dynamic-import and chunk-size warnings.
|
||||
- `git diff --check`: pending after final documentation edits.
|
||||
- `check_project_docs.py`: passed.
|
||||
- `check_doc_drift.py --task-id 20260813-integrate-i2i-client-main-5d9e`:
|
||||
passed after keeping the source task record read-only on its source branch,
|
||||
matching the repository's established Integration Gate pattern.
|
||||
- Packaged desktop and live Works Square/Bailian provider smoke were not run.
|
||||
|
||||
## Follow-ups
|
||||
|
||||
- None recorded.
|
||||
- Replace exact localized quick-reply matching with a structured asset-picker
|
||||
action/purpose before adding more input modes or changing that label.
|
||||
- Run packaged-desktop and live Works Square/Bailian image-to-image smoke after
|
||||
the matching client and server releases are deployed.
|
||||
|
||||
## Promotion Candidates
|
||||
|
||||
|
||||
Reference in New Issue
Block a user