项目创作页与 Agent 工作流

Last updated: 2026-06-11

2026-06-11 Static Render Contract QA

HTML and React/Vite generation now merge an online-safe Static Render Contract QA report into qa_report.renderQa.
The check does not use Playwright in the synchronous online agent path. It inspects the generated HTML source for blank body output, root-only shells without an executable bundle, implementation/mounting instructions, prompt-document previews, missing prompt facts, viewport/title presence, image alt text, and fixed-width overflow risks.
HTML artifacts with static render blockers fail generation before they can become completed previews. React/Vite artifacts keep the existing Vite build QA, add the static source report, and avoid treating normal client-bundle #root output as blank.
The Preview iframe sandbox guard now also injects a lightweight runtime QA probe. It reports body text length, viewport size, scroll overflow, unloaded images, interactive element count, console errors, and runtime errors back to the parent page as qa_report.runtimeRenderQa for immediate Preview review UI.
Runtime QA is debounced through the existing workflow canvas PATCH route and merged into workflow_run_versions.qa_report.runtimeRenderQa; linked saved pages receive the same merged generated_pages.qa_report update. Desktop/mobile dual viewport summaries, screenshot artifacts, and repair automation remain next steps. Playwright should be reserved for CI, background workers, external browser services, or high-fidelity verification instead of the default online path, because the browser-side website Agent cannot directly launch a Playwright-controlled browser.
Retrieved knowledge hits now receive a first-pass static adherence report in qa_report.knowledgeAdherence. It compares each hit's matched section/directive/principle terms against generated HTML/source and records evidence terms, missing terms, and evidence-found / needs-review / missing-signals status. The Preview code tab surfaces this summary in Orson's review checks, and saved work analysis pages show a RAG / Agent evidence node from the linked workflow version. This is an explainability and repair-input layer, not a final design-quality gate.

2026-06-11 Async Browser QA Contract

The online website Agent still must not run Playwright from the browser. The frontend can only render the iframe, run the injected runtime probe, and show results.
High-fidelity browser verification is modeled as an async job result. A worker, CI job, local script, or Browserless-style service opens the generated preview URL or saved HTML with Playwright, captures desktop/mobile screenshots, records console/page errors, checks overflow and blank states, then writes a row into workflow_browser_qa_runs.
workflow_browser_qa_runs stores run/version/page references, user id, source (playwright, browserless, ci, iframe-runtime, manual), status, target viewports, screenshots, console/runtime errors, blocker/warning counts, duration, and worker error text.
Saved work analysis now reads recent browser QA rows for the linked workflow version or generated page and shows them inside RAG / Agent evidence. Private screenshot artifacts receive short-lived signed URLs on the server and render as compact thumbnails when available. This is intentionally a result viewer, not a synchronous generation dependency.
npm run workflow:ops-check is the unified deployment readiness check. It verifies base workflow persistence, Knowledge RAG tables/RPC, Agent task telemetry, async browser QA, screenshot Storage bucket, repair jobs, repair verification columns, and workflow ops metrics, then lists missing migration files.
npm run workflow:browser-qa summarizes production browser QA rows and reports whether the migration is still missing. npm run workflow:browser-qa:run is the local/CI/worker execution script: it can load a generated page, workflow version, URL, HTML file, explicit browser QA run id, or the next queued run; run mobile and desktop Playwright checks; capture screenshots; upload screenshots into the private workflow-browser-qa-artifacts bucket when writing rows; and write/update a workflow_browser_qa_runs row.
npm run workflow:browser-qa -- --format=repair-candidates converts failed browser QA rows into compact repair candidates with target ids, priority, viewport metrics, screenshot storage metadata, issue labels, and a repairBrief. This is the current bridge from async Playwright evidence to human-reviewed targeted repair; the detailed queue contract lives in docs/WORKFLOW_BROWSER_QA_REPAIR_QUEUE.md.
workflow_repair_jobs now persists that bridge as a queue table. npm run workflow:repair-jobs summarizes backlog health; npm run workflow:repair-jobs:enqueue is dry-run by default and --write=true inserts new queued jobs, deduplicated by browser_qa_run_id; npm run workflow:repair-jobs:run exports one queued/specified job as a full repair context package with prompt, HTML, project files, QA evidence, and guardrails; npm run workflow:repair-jobs:verify closes jobs from post-repair browser QA evidence and only marks completed when the verification QA has no blockers/runtime errors. Saved work analysis pages show recent repair jobs beside browser QA evidence. This is still repair intake, verification, and observability, not automatic code mutation.
npm run workflow:browser-qa:worker wraps the single-run script for cron, bounded batch, or long-running worker use. --once=true consumes one queued row, --max-runs=<n> runs a bounded batch, and --keep-alive=true --poll-ms=5000 polls continuously.
Product-side queue creation is env-gated with WORKFLOW_BROWSER_QA_AUTO_ENQUEUE=true. When enabled, workflow stream/background generation and explicit Save Work enqueue a queued browser QA row after previewable HTML exists. This remains a queue contract, not an in-request Playwright run. Deploying the worker in an environment with Playwright/Browserless and adding a model repair worker that consumes workflow_repair_jobs remain next steps.

2026-06-03 Workflow Consistency Fixes

Orson QA blockers are now merged with hard server blockers; any blocker keeps the plan from passing the code-generation gate.
Default full planning now includes Elara as an implementation-constraints reviewer. Targeted @Elara revisions still run the Programmer subagent before code generation and merge implementation implications back into the website template and prompt payload.
Persisted standard workflow graphs now match the current compact canvas: Design System / Content & IA / Skills -> Full Prompt -> Code -> Prompt QA -> Preview. PM Hub / Overview remains a pinned workbench outside the saved React Flow graph.
Agent planning now carries a role-specific AgentInputContract and returns optional agentArtifacts for Mira, Cleo, Isolde, Sable, Elara, and Orson through existing artifact payloads and input_snapshot.
Orson remains the owner of failed Prompt QA reports; QA blockers are no longer reassigned to Mira in the UI.
Targeted mention routing now supports Chinese aliases such as @设计师, @内容, @技能, @前端, and @质检.

2026-05-20 Agent Team Workflow Refresh

The creation page now uses a PM Hub plus compact Agent workspaces, and ordinary briefs are planned by role-specific model calls.

PM chat and Overview are merged into PM Hub / Intent Overview; the visible Input canvas node is removed. The bottom composer remains for input, assets, model choice, and sending only.
Designer, Content Architect, Skill Manager, and QA Reviewer workspaces are compact by default. Their collapsed state shows agent avatar, status, latest report, and summary; expanding opens an internal scroll panel with a fixed height.
Full Prompt, Code, Prompt QA, and Preview are separate workflow stages. Programmer owns the Code node and the Preview Code tab during generation.
Agent status chatter no longer appears as bottom conversation messages. agent:step, artifact:complete, questions, plan confirmation, and blocker reports update WorkflowReport cards inside the relevant node.
The standard website graph is now design-system / site-architecture / skill-recommendation -> site-template -> code -> prompt-qa -> preview; PM Hub / Overview remains a pinned workbench and old drafts that still contain input are remapped at load time.
Ordinary brief planning now runs as PM Planner, Designer Planner, Content Planner, Skill Manager Planner, and QA Reviewer stages in the same workflow process. This is role-based orchestration, not a persistent multi-subagent runtime.
Template contamination guards block internal planning phrases such as Use the exact colors, User brief:, problem / process / outcome, and placeholder instructions from Design System, Content, and Full Prompt output.
Dashboard and ecommerce-dashboard detection now produces real dashboard planning for prompts like 帮我生成一个电商数据看板, including GMV, orders, conversion, channel ROI, product ranking, funnel, filters, tables, and export/detail actions.

2026-05-18 Prompt Intelligence Agent

The creation page now runs through start -> awaiting_plan_confirmation -> confirm_plan.

Default discussion mode pauses after Intent Map, Decision Board, Capability Fit, Design System Hub, Prompt Template, and Prompt QA are visible. The composer Auto toggle lets the agent auto-confirm the recommended direction when Prompt QA passes.

Design System is panelized into reusable designSystemPanels and designSystemTokens, with trace fields stored on workflow versions and generated pages.

2026-05-17 Website Mode Workflow

The project creation workspace uses a fixed left Agent panel plus a React Flow infinite canvas on the right.

The left Agent panel now has three creation modes: 网站 / Website, PPT, and 移动应用 / Mobile App.
Only Website mode is implemented in this release. PPT and Mobile App are visible but disabled as future workflows.
Website mode initializes the right canvas with a node framework: Overview, Skills, Design System, 网站架构, section-level 内容输入, 约束/Constraints, Full Prompt, Code, Prompt QA, and Preview.
Preview sits on the right as a large webpage-ratio window. It owns two tabs: 代码 / Code for source output while generation is running, and Preview for the final iframe render after generation completes.
Website Architecture is a selectable section builder. It starts from an add-section control, lets each section choose from built-in common types such as Hero, Feature, Gallery, Pricing, FAQ, CTA, and Footer, and creates a matching content input card connected from the section node.
Design System and Full Prompt render default section blocks instead of a single empty text area.
The old composer Skill button was removed. Skill selection now lives in the right-side Skills recommendation card, which combines Agent recommendations with user selection.
Technical stack information moved into Overview. The former Tech Stack & Constraints card is now user-facing 约束 / Constraints, focused on Do, Don't do, counterexamples, and acceptance criteria.
Workflow edges are present as the default layout language: idle edges are translucent, active edges animate while generation streams, and completed edges turn solid white.
Canvas cards can be dragged and resized. Pan, zoom, minimap, fit view, and controls are provided by @xyflow/react.
The right workspace height is aligned with the left Agent panel. Manual right-click node creation and manual handle-to-handle connection are not part of the user path.
Full Prompt now means the compiled website-generation prompt produced from planning nodes. Internally, siteTemplate stores the structured Website Generation Template and fullPrompt remains the final code-generation prompt for compatibility.
Website Architecture and Content Input cards support user editing so planning content can be carried into later prompt compilation.
The standard website generation route is now a fan-in graph:

design-system / site-architecture / skill-recommendation -> site-template -> code -> prompt-qa -> preview, with section-level content input cards branching from individual Site Architecture sections.

During SSE generation, node:start:code automatically switches the Preview window to the Code tab. artifact:complete:preview switches it back to the Preview tab; users can manually switch tabs afterward.
Long full-production prompts become a structured website template before code generation. DeepSeek and very long full prompts use a server-extracted template to avoid another large JSON model call; other providers may still use model-based template conversion.

Persistence:

workflow_run_versions.workflow_graph and generated_pages.workflow_graph store canvas nodes, positions, sizes, statuses, and edges.
site_architecture, content_input, and site_template are stored beside full_prompt, html_code, project_files, build_log, and qa_report.
The client debounces canvas graph saves through PATCH /api/generate/workflow/canvas.
input_snapshot.workflowGraph is also written as a schema fallback.

这份文档记录 /zh/create/new 项目创作页和对应 Agent 能力的当前设计。它和页面实现、Agent 编排、维护记忆绑定：只要项目创作页或 Agent 工作流发生用户可见的功能变化，就要同步更新本文档和 docs/PROGRESS.md 里的 Maintenance Memory。

当前定位

项目创作页是 Interface Lab 从“浏览/学习作品”进入“生成新项目”的核心工作台。用户在这里选择创作模式、输入需求、选择模型和 Skills、添加参考素材，并让 Agent 先生成 PM Hub 与各角色工作区，再生成 Full Prompt，最后在同一个 Preview 窗口里查看代码和预览。

主要入口：

页面：/[locale]/create/new
客户端组件：src/components/project-workflow.tsx
右侧画布与连线：@xyflow/react rendered in src/components/project-workflow.tsx
Agent 编排：src/lib/generation/workflow.ts
SSE 路由：src/app/api/generate/workflow/stream/route.ts
素材路由：src/app/api/generate/assets/route.ts

输入与控制区

左侧栏采用固定全高的输入与控制布局，保持和工作台一致的左侧菜单体验。Agent 工作汇报不再堆在输入区，而是显示在对应画布节点内：

默认只保留 Agent 标识、当前模型、三段创作模式按钮、权限提示、主输入框和底部小图标按钮。
三段创作模式是网站、PPT、移动应用；当前只开放网站，另外两个显示 future/coming soon。
素材入口合并进统一输入框：附件按钮只负责打开文件选择，图片可以直接粘贴，文件可以拖拽到输入器。
模型选择保留在底部弹出选择器里；所有模型展示名统一带 Pro 后缀。
Skills 不再通过底部按钮打开，改到右侧 Skills 推荐卡片里选择。
底部圆角输入器固定承载主输入、素材按钮、模型按钮、语音入口占位和发送/修改按钮。
PM 沟通、澄清问题、错误提示和需求摘要主要进入 PM Hub / Overview 节点，避免常驻反馈流挤占输入空间。
Agent 对话里的长消息会折叠显示，并且链接会在气泡内换行，避免 URL 冲出对话框。
未登录或无 Pro 权限时，用户仍可编辑文本、选择模型、选择 Skills 和切换模式；上传、发送、生成、修改仍需要 Pro/admin。

用户输入能力

创作页支持以下输入：

文字需求：页面目标、用户、内容模块、风格、交互、动效和约束。
链接：直接粘贴在输入框中，提交时自动识别公开 URL，通过素材 API 抓取公开网页文本并加入 Agent 上下文。
代码片段：直接粘贴在输入框中作为用户需求上下文，不再需要单独选择代码类型。
文件和图片：可以通过附件按钮选择、拖拽到输入器或直接粘贴图片，上传到私有 Supabase Storage bucket workflow-assets 并创建素材记录。
Skill 选择：在右侧 Skills 推荐卡片中完成，最多选择 8 个 Prompt Skills；Agent 推荐项和用户已选项会合并展示。
模型选择：当前页面支持 DeepSeek、Gemini、GPT 和 Claude 兼容模型选项，选择器以弹出列表展示，模型名称统一使用 Pro 后缀。

创作模式

对话框顶部有三个创作模式：

网站：当前已实现。右侧画布显示网页生成节点框架，Agent 按节点推进规划、模板、代码和预览。
PPT：未来工作流入口，当前禁用。
移动应用：未来工作流入口，当前禁用。

旧的 discussion/auto 字段仍作为内部兼容字段保留，但不再作为主界面模式暴露。澄清问题由 Agent 根据网页规划质量决定。

实时节点与连线

页面由 /api/generate/workflow/stream 返回的 SSE 事件驱动，不再依赖固定 sleep 模拟流程。

核心事件类型：

run:start
node:start
edge:activate
artifact:delta
artifact:complete
question
awaiting_style_confirmation
save:complete
run:error
run:complete

前端 reducer 根据事件更新节点状态、连线状态、卡片内容和预览。节点状态包括：

idle
queued
streaming
asking
awaiting-confirmation
modifying
complete
error

当前网站工作流

用户输入需求和素材。
右侧画布已经有网站节点框架和半透明默认连线。
PM Planner 先解构输入，更新 PM Hub / Overview：需求摘要、页面类型、目标、缺失信息和决策摘要。
Skill Manager 只从真实 Skill 库中查询和推荐最多 8 个 Skills。
Designer 生成 Design System、面板和 token。
Content Planner 生成网站架构、内容输入、标题、CTA、SEO/alt 文案和模块说明。
Full Prompt 由角色产物汇总生成，并激活进入 Prompt QA 的连线。
QA Reviewer 检查 Prompt 质量、模板污染、阻断项和是否允许进入代码生成。
如果关键信息缺失或 QA 阻断，对应报告显示在 PM Hub 或 Prompt QA 节点，并允许用户继续输入。
QA 通过后，Full Prompt 进入 React/Vite 或 HTML 代码生成路径，并激活 Prompt QA -> Preview 连线。
代码生成过程中 Preview 窗口自动切到 代码 tab；预览 artifact 完成后自动切回 Preview tab，之后用户可手动切换两个 tab。
生成结果先保存为 workflow_run_versions 草稿；用户点击右上角 Save work 后才发布到 generated_pages。

修改模式

已有生成结果后，用户继续输入修改要求，Agent 进入 revision 流程：

读取当前 workflow version。
激活 Change Request -> Design System。
修改 Design System。
修改 Full Prompt。
在 Preview 窗口的 代码 tab 中显示修改后的代码输出。
更新 Preview tab 中的最终预览。
保存新的 workflow version 草稿；如果该 workflow 已关联作品，用户保存时选择更新同一作品或发布新作品。

修改过程中，对应节点使用 modifying 状态显示修改动画。

数据和持久化

生成稳定性

普通 brief 的生成链路现在拆成角色规划和代码生成，避免单次大 JSON 把内部模板说明当成用户可见产物：

PM Planner：runWorkflowPlan 生成标题、overview、意图判断、缺失信息和决策摘要。
Designer Planner：生成 Design System、designSystemSections、设计面板和 tokens。
Content Planner：生成网站架构、内容输入、section copy、CTA、SEO/alt 文案和模块说明。
Skill Manager Planner：只从真实 Skill catalog 里选择和解释最多 8 个 Skills。
QA Reviewer：检查 Full Prompt 质量、模板污染、阻断项和是否允许进入代码生成。
HTML / React-Vite 代码生成：QA 通过后才进入 Preview 的代码生成路径。
授权继续：当用户在追问后明确表示“你设计一套就可以”“没有要求”“你自己设计”等，SSE 路由会跳过下一轮 intent 追问，直接进入生成。

这套拆分适用于 DeepSeek、Gemini、GPT 和 Claude 兼容模型，减少空响应、截断响应、模板污染和 Model response was not valid JSON 错误。完整 production prompt 仍走 direct full-prompt 保护路径。

DeepSeek 长 Prompt 处理

2026-05-16 的 DeepSeek 故障复盘记录在 docs/DEEPSEEK_WORKFLOW_INCIDENT.md。

当前处理方式：

deepseek-* 模型会明确走 DeepSeek provider，不再因为空响应隐式回退到 PackyAPI；只有配置 LLM_EMPTY_RESPONSE_FALLBACK_MODEL 时才允许显式 fallback。
完整实现类 prompt 会跳过重复 intent 澄清，直接进入 direct full-prompt generation。
direct full-prompt generation 不再要求 brief 返回 JSON，而是先生成 plain-text brief，再并行请求 CSS 和 body HTML；少量 JS 只在 prompt 明确需要交互、轮播、滚动联动或表单等运行时行为时生成，最后由服务端组装 preview HTML。
direct full-prompt generation 会把 prompt 中的 Google Font 链接写回 HTML head，并把关键可见文案、媒体 URL、字体链接和颜色作为 mustPreserve 约束传给模型。
body HTML 阶段会拒绝 #root、createRoot、ReactDOM 等 React/Vite 空壳预览，服务端也会检查 root-only 或近空白 HTML，并触发 repair 请求。
如果组装后的 preview 漏掉 prompt 中的重要引号文案，服务端会触发一次 body quality repair。
SSE 会在生成过程中按网站节点顺序激活连线，让用户看到 Agent 正在从需求拆解、规划、模板、代码到预览逐步推进，而不是由用户手动连接节点。

当前方案是稳定性补丁，不是最终质量方案。下一版应优先加入 render QA、DOM/console/screenshot 检查、局部 repair、fast/high-fidelity 模式、后台任务和分步骤耗时记录。

React/Vite full-prompt artifact path

As of 2026-05-16, DeepSeek full implementation prompts default to artifactKind="react-vite" when WORKFLOW_REACT_VITE_ENABLED is not false.

The server sends the original full prompt directly to the model instead of compressing it into a brief.
The default first pass is component-sharded: DeepSeek generates src/components/Hero.tsx, src/components/ContentSections.tsx, and src/index.css as smaller stage calls. The server writes the tiny src/App.tsx composition shell. This keeps the full prompt in each model call but avoids requiring DeepSeek to return the whole project in one giant response.
The model must return marker-based files: src/App.tsx, src/index.css, optional src/data.ts, and optional src/components/*.tsx.
The server owns index.html, src/main.tsx, Tailwind/PostCSS/Vite config, and package.json.
Dependencies are fixed to the repo whitelist: react, react-dom, vite, @vitejs/plugin-react, tailwindcss, postcss, autoprefixer, framer-motion, and lucide-react.
A temporary Vite project is built on the server. The built JS/CSS are inlined into html_code, so the existing Preview iframe, saved works, community cards, and analysis pages remain compatible.
Source files and diagnostics are stored in project_files, artifact_kind, build_log, and qa_report on both workflow_run_versions and generated_pages.
After build QA, the server also adds qa_report.renderQa from the Static Render Contract QA layer. This records source-level render metrics and warnings without requiring a browser in the synchronous online workflow.
Build failure or prompt-fact QA failure triggers at most one model repair. If repair still fails, the workflow returns a clear error rather than a local placeholder page.
WORKFLOW_REACT_VITE_STRATEGY=split or WORKFLOW_REACT_VITE_SINGLE_CALL=true can opt back into larger-output modes, but the default is the safer component-sharded path.

The Preview window's Code tab displays file names and source content for react-vite artifacts. Ordinary discussion/brief runs continue to show the final HTML in that same Code tab.

Agent 内置流程 Skill

实时节点和连线规则不是用户可选 Skill，而是内置隐藏的 Workflow Orchestrator Skill。它固定注入 Agent 系统提示中，让 Agent 掌握：

Current canonical website graph: design-system / site-architecture / skill-recommendation -> site-template -> code -> prompt-qa -> preview. PM Hub / Overview is pinned outside the saved graph, and agentArtifacts preserve role-owned input/output/blocker provenance.
节点图：PM Hub / Overview、Skills、Design System、Site Architecture、Prompt QA、Full Prompt、Preview。Code 是 Preview 窗口内的 tab，不再是独立画布节点；旧 draft 中的 Input 会映射回 PM Hub。
网站模式的固定规划顺序，以及 PPT / Mobile App 作为未来工作流入口的约束。
缺失信息必须落到 PM Hub 或对应规划节点，并用选项式追问呈现。
Design System、网站架构、内容输入和 Prompt QA 必须输出稳定结构，不能包含内部模板说明。
修改时必须保留已有产品意图，并按规划节点、Full Prompt、Prompt QA、Preview 内 Code tab、Preview tab 顺序推进。

用户可选 Skills 仍然只表示设计、动效、布局、组件等局部 Prompt 能力。

维护规则

以下改动必须同步更新本文档和 docs/PROGRESS.md 的 Maintenance Memory：

/[locale]/create/new 页面交互发生用户可见变化。
Agent 模式、节点、连线或 SSE 事件协议改变。
输入类型、素材处理或权限规则改变。
workflow_runs、workflow_run_assets、workflow_run_versions 或 workflow-assets 的 schema/RLS 改变。
生成、规划确认、修改、保存版本、模型输出拆分或解析兜底的流程改变。

如果只修改视觉样式但不影响能力边界，也至少要在开发日志里记录；如果改变用户理解和使用 Agent 的方式，就必须更新本文档。

显式保存模型

截至 2026-05-14，/[locale]/create/new 是 workflow-draft first：

Agent 生成只写入 workflow_runs 和 workflow_run_versions。
生成预览不会自动进入“我的作品”，必须由用户点击 Save work。
POST /api/generate/workflow/save 将当前 workflow version 发布到 generated_pages。
首次保存直接发布为一个新作品。
当 workflow 已关联某个作品时，保存时提供两个选择：更新同一作品，或发布为新作品。
账号页的 My Projects 支持删除 generated_pages，以及将某个 saved work 发布为公开 Community 模板。社区发布使用稳定 slug community-<generatedPageId>，重复发布会更新同一个模板。
generated_pages.workflow_run_id 和 generated_pages.workflow_version_id 将作品分析页连接回可编辑 workflow。
workflow_run_versions.input_snapshot 保存 messages、selected skills、model、asset ids 和 asset summaries，使 /create/new?work=<generatedPageId> 可以恢复 workflow。
作品分析页优先使用关联 workflow version 的字段，而不是依赖 fallback 拼接；如果存在 RAG/Agent evidence，会显示知识命中、证据信号和各角色 artifact 摘要。

Project Workflow Agent