docs: integrate design stream and quote handoff
Some checks failed
Electron E2E / Electron E2E (macos-latest) (push) Has been cancelled
Electron E2E / Electron E2E (ubuntu-latest) (push) Has been cancelled
Electron E2E / Electron E2E (windows-latest) (push) Has been cancelled

This commit is contained in:
2026-09-04 11:46:11 +08:00
parent 23f96a523e
commit 336e0bb0ca
4 changed files with 140 additions and 5 deletions

View File

@@ -26,7 +26,7 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
| Official Hosted Plugins | Acquired code-owned bundled Game Resource package → effective parent snapshot → code-owned Main adapter → fixed Works Square hosted route | 无设备下载、更新、Beta 或签名步骤Renderer/Package/Pi 不持有 Provider key、model 或 URL。每次计费操作要求显式确认child 不继承 hosted tool。历史 Hosted Web Search 不再进入当前客户端。 |
| Device Packages | Conversation install tools → Main-owned inspect/preview/confirm/commit → immutable local generation → parent Skill/Pi-extension resources | 支持 npm、Git、绝对本地 Plugin 目录与 loose `SKILL.md`没有可见安装入口、Account Library、Release、Admission 或 Marketplace Package Store。可执行 extension 拥有桌面用户权限且生命周期脚本禁用。每个 generation 包含所有显式安装且当前启用的 Skill/extension新/idle parent 自动刷新active parent 在 turn settled 后刷新child 始终为空。 |
| AI Design Workspace & Living Form | 一个 Workspace 的当前 Direction、Current Specification、持久 Agent Session、conversation timeline、Tasks 与 Assets | 自然对话是主创作面Living Form 仅以“AI 已理解”的紧凑辅助摘要与可选手动调整投影服务端 Current SpecificationRenderer 只持有草稿和已接受投影 |
| AI Design Input & Reconciliation | Chat、字段/集合编辑、decision、proposal、lock、Asset binding 与 restore | 全部进入同一 `design.input.apply` reducer稳定 command/operation ID 支持 unknown-result 重放revision conflict 刷新权威状态;待提交 chat 从同一 pending operation 临时投影,raw assistant delta 保持内部且不生成对话区进度栏 |
| AI Design Input & Reconciliation | Chat、字段/集合编辑、decision、proposal、lock、Asset binding 与 restore | 全部进入同一 `design.input.apply` reducer稳定 command/operation ID 支持 unknown-result 重放revision conflict 刷新权威状态;待提交 chat 从同一 pending operation 临时投影assistant delta 只能在匹配该 operation 的一个未完成助手气泡中临时绘制且不生成独立整理进度栏 |
| AI Design Gateway Routing | Main-owned Works Square V2 adapter 与 Direction event stream | Main 持有 Works Token、stream ticket、WebSocket、重试分类和错误脱敏事件顺序与 Task progress 不构成 Specification 真值 |
| 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 保存 |
@@ -89,7 +89,7 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
- Main-owned Canvas Workspace JSON 请求和 shared Works token refresh 的完整生命周期最多 30 秒,超时 abort transport 并以固定 `504 DESIGN_WORKSPACE_REQUEST_TIMEOUT` 结束 Renderer 等待。Electron `net.fetch` 失败后的 Node fetch 透明回退只允许 `GET``HEAD``OPTIONS`PATCH/POST 等 mutation 只允许由持有显式幂等身份的上层协议决定重试,不能由底层 transport 隐式重放。该边界不改变上面的 WebSocket→REST 幂等 fallback。
- Renderer 的异步与流式结果必须核对 Workspace、Direction、revision 和 operation identityDirection snapshot 是 Specification 真值Task/Asset 事件只更新 Workspace resource projection。
- 待提交 chat 可以从现有 pending operation 立即投影为明确标注“发送中/正在确认”的用户气泡,但只有服务端 canonical turn 能进入对话历史;确定失败必须恢复原草稿,不能另建一套消息状态或新业务意图。
- `design.assistant.delta` 是未完成的内部传输状态,不是助手回复。Renderer 不得显示原始片段,也不得在对话区为它创建独立整理进度栏;右侧 Current Specification 投影继续呈现 AI 当前理解。重叠连接与重放 chunk 必须按连接 generation 和 `chunkIndex` 收敛。
- `design.assistant.delta` 是未完成的传输状态,不是 canonical assistant turn。Renderer 只能把它临时绘制为与同一 pending chat identity 绑定的单个未完成助手气泡,并在该 operation 确定收敛后由 canonical turn 替换不得持久化为第二条消息、伪装为已完成回复或创建独立整理进度栏。unknown outcome 保留原 identity 与已有片段,其他 operation 的更新不得全局清除它;右侧 Current Specification 继续呈现 AI 当前整理出的设计理解。重叠连接与重放 chunk 必须按连接 generation 和 `chunkIndex` 收敛。
- 确认生成只提交不可变 Quote ID。Task 事务已提交但事件迟到时可刷新 Workspace projectionTask progress 不得改写 Living Form 或授权新的生成操作。
- Updater feed 选择、原始错误日志、下载和安装生命周期只属于 Electron Main。Renderer 不得把缺失稳定 manifest 投影为“已是最新版”也不得显示原始堆栈、URL、路径或错误码并发检查共享同一错误事件时只发送一次错误状态后续独立重试仍可重新报告。
- 图片与视频复用同一个单图来源选择器。图片 Brief 可从当前 Workspace 的已完成作品或本地上传中选择一张参考图继续生成;视频 Brief 使用同一入口绑定首帧。两条路径都必须通过现有 Workspace Asset 上传/选择契约提交一个真实 `attachmentAssetIds`,不得用本地路径或自然语言描述代替资产身份。

View File

@@ -4,6 +4,27 @@ This file is the integrated default-branch snapshot. Feature tasks record progre
## Integrated Through
- AI Design streamed-reply diagnosis
`229b1b1ce39b7f1541a93ea3c980ab82b6d6266c` and client fix
`23f96a523eb37d8397bb3766ce95a59d56e59225` from tasks
`20260904-diagnose-design-stream-6a4e9c21` and
`20260904-fix-design-stream-4f7b91c2` are integrated onto local `main` and
canonically reconciled by task `20260904-integrate-design-stream-5e7c2a91`.
The existing post-validation `design.assistant.delta` transport is visible again as
exactly one provisional assistant-shaped bubble tied to its pending chat identity;
canonical `workspace.turns` still owns history and replaces the unfinished bubble,
while unknown outcomes keep the same identity and partial reply. The removed generic
“AI 正在整理你的想法” banner is not restored. A ready conversation now offers an
inline Quote step; successful Quote requests reveal the confirmation on desktop or
open it on mobile, but only explicit immutable Quote-ID confirmation creates a paid
Task. Unknown Quote requests disable both entry points and retry the original
operation. Focused tests passed 35/35, the Electron Quote-confirm-Task flow passed
1/1, typecheck, scoped lint, Vite build, document gates, and independent review
passed. The ordinary full suite had one unrelated Pi real-process 2-second timing
miss among 1,873 passing tests and 2 skips; that exact test passed immediately in
isolation, and the pressure test passed 1/1. Provider-native first-token streaming
remains a separate server follow-up; no server, database, billing, Plugin,
packaging, deployment, publication, or remote push changed.
- AI Design conversation-feedback sources
`403236115bf81e7617856cd8219b1be23f6abbb8` from task
`20260904-design-summary-separation-9c4e7a21` and

View File

@@ -0,0 +1,114 @@
# Task: Integrate AI Design streamed replies and quote handoff
## Identity
- Task ID: 20260904-integrate-design-stream-5e7c2a91
- Mode: Integration
- Branch: codex/20260904-diagnose-design-stream-6a4e9c21-diagnose-design-stream
- Worktree: D:\Datas\OthersProjects\.codex-worktrees\makelore\20260904-diagnose-design-stream-6a4e9c21
- Base commit: 23f96a523eb37d8397bb3766ce95a59d56e59225
- Owner: codex-root
- Status: Ready for Integration
## Scope
- Integrate diagnosis commit `229b1b1ce39b7f1541a93ea3c980ab82b6d6266c`
and implementation commit `23f96a523eb37d8397bb3766ce95a59d56e59225`
from tasks `20260904-diagnose-design-stream-6a4e9c21` and
`20260904-fix-design-stream-4f7b91c2` onto local client `main`.
- Reconcile the accepted promotion candidate into `current-state.md`, the AI Design
architecture boundary, and business rules: a delta may appear only as one visibly
unfinished assistant reply; Quote review remains separate from paid generation
confirmation.
- Preserve the three known foreign untracked task records in the root checkout exactly
as found. Do not modify the Works Square server, billing, Plugin navigation,
packaging, publication, remote refs, or any unrelated client feature.
## Intent And Constraints
- The user explicitly requested this completed client fix be merged to the main branch
and had already confirmed the product decision behind the canonical wording change.
- Root `main` was verified at exact head
`aa3f52a8f8414c9ad939d396bd2828c3e07c70e7`, with only the three previously known
untracked records. The source is a linear descendant of that frontier, so use a
fast-forward after canonical reconciliation; do not stash, reset, clean, add, or
adopt the foreign records.
- Keep `workspace.turns` as canonical conversation history. The provisional stream is
presentation tied to an existing pending chat identity, never a second completed
turn or generic progress banner.
- Keep production authorization two-step: Quote request/reveal may be prompted by the
conversation, while only explicit confirmation of the immutable Quote ID creates a
paid Task.
## Project Context Loaded
- Concurrent Task Gate passed for integration task
`20260904-integrate-design-stream-5e7c2a91`, owner `codex-root`, mode Integration,
branch `codex/20260904-diagnose-design-stream-6a4e9c21-diagnose-design-stream`,
worktree
`D:\Datas\OthersProjects\.codex-worktrees\makelore\20260904-diagnose-design-stream-6a4e9c21`,
base `23f96a523eb37d8397bb3766ce95a59d56e59225`; the repository Integration lock is held.
- Loaded the startup memory set, current integrated state, system overview, business
rules, ADR-007 context, and both completed source task records including outcome,
verification, follow-up, and promotion candidates.
- Relevant active peers are unrelated historical/stale task records. The exclusive
Integration lock prevents concurrent canonical reconciliation; no peer owns a
conflicting current AI Design product decision.
- The old canonical rule hid raw delta text entirely. The accepted source narrows that
rule without weakening authority: exactly one provisional bubble may paint the
already validated assistant text, while canonical turns, Current Specification,
stable operation identity, Quote identity, and explicit payment confirmation remain
unchanged. The user's confirmation resolves the semantic conflict.
- Planning Gate result: Passed.
## Plan
1. Reconcile the accepted AI Design stream/Quote behavior into canonical architecture,
business rules, and current-state integration evidence.
2. Re-run task-aware document and source verification at the final integration head.
3. Commit the integration record, fast-forward exact root `main`, verify the three
foreign untracked files are unchanged, then complete and release the Integration
lock.
## Outcome
- Accepted and reconciled both source tasks on top of exact local `main` frontier
`aa3f52a8f8414c9ad939d396bd2828c3e07c70e7`; their commit chain is linear and
contains no unrelated product changes.
- Updated the canonical architecture and business rules to distinguish one
operation-bound unfinished assistant bubble from canonical conversation history
and from the prohibited generic progress banner. Unknown operations retain their
identity/partial text and cannot be erased by unrelated updates.
- Recorded the ready-conversation Quote handoff: desktop reveals the offered Quote,
mobile opens it, and neither path creates a Task until the user explicitly confirms
the immutable Quote ID. Unknown Quote requests keep and retry the original operation
instead of creating another intent.
- Updated `current-state.md` with source commits, behavior, verification, the known
post-validation streaming limitation, and the explicit no-server/no-billing scope.
- Prepared the integrated branch for a fast-forward of root `main`; the root's three
pre-existing untracked task records remain outside this commit and are not adopted,
staged, modified, moved, or deleted.
## Verification
- Source task evidence: focused 35/35, Electron Quote-confirm-Task 1/1, typecheck,
scoped ESLint, Vite build, diff check, pressure 1/1, and independent final review
passed. The full suite's only miss was an unrelated Pi process 2-second timing check,
which passed immediately in isolation.
- Integration-head rerun: focused Renderer/store/Card suite 3 files / 35 tests passed;
`pnpm exec tsc --noEmit` passed.
- Integration-head Electron flow passed 1/1 and again exercised the conversation CTA,
Quote visibility, explicit 12-Design-Point confirmation, and queued Task projection.
- `git diff --check`, `check_project_docs.py`, and task-aware
`check_doc_drift.py --task-id 20260904-integrate-design-stream-5e7c2a91` passed.
## Follow-ups
- Provider-native first-token streaming still requires a separately scoped server
contract; this integration only exposes the existing validated-message chunk
projection honestly.
## Promotion Candidates
- None. The source candidates were accepted by the user and applied to canonical
architecture, domain rules, and current state in this integration task.

View File

@@ -100,11 +100,11 @@
- 每个 mutation 使用稳定 command 与 semantic operation identity。transport-unknown 只能重放原命令business rejection、timeout 或用户再次点击不能自动生成新的业务意图。
- Direction projection 是 Specification 真值。event cursor、assistant delta、Task progress 与 Asset event 只用于传输/资源收敛,不得推进或覆盖 canonical specification revision。
- 用户提交 chat 后,客户端可以立即把同一个 pending operation 投影为临时用户气泡,并明确显示“发送中”或“正在确认”;只有服务端返回的 canonical turn 才进入 conversation timeline。确定失败时必须让原草稿重新可编辑不得把临时投影持久化为第二条消息。
- `design.assistant.delta` 只用于内部传输和结果收敛;原始片段不得作为完成的助手回复展示,对话区也不得为其增加独立的整理进度栏。AI 当前整理出的设计理解由右侧 Current Specification 投影承载;连接重叠或事件重放按 connection generation 与 `chunkIndex` 去重收敛。
- `design.assistant.delta` 只用于未完成回复的传输和结果收敛,不得进入 canonical conversation timeline。客户端可以把它临时显示为与同一 pending chat identity 绑定的单个未完成助手气泡;确定收敛后必须由 canonical turn 替换unknown outcome 则保留原 identity 与已有片段不得把片段伪装为完成回复、持久化为第二条消息、因其他 operation 更新而全局清除,或另加独立的整理进度栏。AI 当前整理出的设计理解由右侧 Current Specification 投影承载;连接重叠或事件重放按 connection generation 与 `chunkIndex` 去重收敛。
- Main 只向 Renderer 投影已知错误码的固定中文提示未知上游错误文本必须脱敏为通用提示Works Token、stream ticket、provider internals 留在 Main/服务端。
- AI 绘画 Workspace JSON 请求与 shared Works token refresh 必须覆盖取凭据、发请求和读取响应 body 的完整 30 秒 deadline即使底层 transport 忽略 abort调用方也必须确定性结束为 `504 DESIGN_WORKSPACE_REQUEST_TIMEOUT` 并释放共同等待者。Electron-to-Node 透明 fallback 仅允许 `GET`/`HEAD`/`OPTIONS`mutation 不得因 transport failure 被隐式重放,任何重试必须由上层显式幂等合同授权。
- `design.quote.request` 必须绑定 exact current Specification revision 并返回 immutable Quote任何 production-meaning edit 都需要新 revision 与新 Quote。
- `design.generation.confirm` 只提交 Quote identity。客户端不编辑 provider Prompt/model/route/storage不计算 Token Points也不把 Task recovery 当作再次确认授权。
- `design.quote.request` 必须绑定 exact current Specification revision 并返回 immutable Quote任何 production-meaning edit 都需要新 revision 与新 Quote。对话或 Current Specification 就绪态可以引导用户请求并查看 Quote桌面端可定位到报价区、移动端可打开报价面板但该动作不得创建 Task。
- `design.generation.confirm` 只提交用户明确确认的 Quote identity。客户端不编辑 provider Prompt/model/route/storage不计算 Token Points也不把聊天就绪文案、Quote 展示、重复点击或 Task recovery 当作生成授权。
- 图片/视频 source 必须是当前 Workspace 的 canonical Asset并通过 typed binding 进入 Specificationmedium/role 决定用途,不得从 quick-reply 文案、V1 Brief 或本地路径推断。
- Task/Asset reconciliation 只能更新 Workspace resources已经落库但事件迟到的 Task 可通过 refresh 恢复,不能覆盖 Living Form、local drafts 或 pending Design input。
- 删除 Canvas 项目必须要求用户完整输入项目名并通过 Main-owned Workspace DELETE。成功后被删 Workspace 的会话、任务和资产不得继续留在 Renderer 可访问状态;服务端决定软删除、任务取消、预留积分释放和运行中任务结算。