Initial TrueGrowth source import

2026-07-07 09:36:36 +08:00
commit 3b6781d695
2283 changed files with 691996 additions and 0 deletions
--- a/openspec/changes/add-stitch-design-workflow/design.md
+++ b/openspec/changes/add-stitch-design-workflow/design.md
@@ -0,0 +1,133 @@
+## Context
+
+`opentu` 当前的前端结构以编辑器能力为中心，`apps/web/src/app/app.tsx` 负责应用初始化、工作区恢复、URL 状态、崩溃恢复、安全模式等应用级装配；`packages/drawnix/src/drawnix.tsx` 承担核心白板编辑器、工具栏、抽屉、AI 面板、媒体库、项目切换等大量交互能力。
+
+这意味着并不是所有 UI 都适合先进入 Stitch：
+
+- 编辑器核心区域高度依赖本地状态与插件链
+- 外围页面和面板则更接近典型的“信息架构 + 视觉布局”问题，适合由 Stitch 提供方案探索
+
+如果不先定义边界，Stitch 很容易被误用为“直接产出生产代码”的工具，导致设计稿与业务实现失去可维护性。
+
+## Goals / Non-Goals
+
+- Goals:
+  - 为 `opentu` 建立一条可重复使用的 Stitch 设计闭环
+  - 让仓库内持久化保存设计系统上下文与 screen 映射
+  - 优先提升外围页面、抽屉、弹窗、空状态页的设计探索效率
+  - 保持代码实现为交互逻辑与生产行为的唯一真源
+- Non-Goals:
+  - 本次不让 Stitch 直接接管核心白板编辑器 UI
+  - 本次不把 Stitch 生成的 HTML 直接作为生产代码运行
+  - 本次不要求一次性覆盖所有前端页面
+
+## Decisions
+
+- Decision: Stitch 只主导“受边界约束的页面与面板”
+
+  - 优先覆盖弹窗、设置面板、项目抽屉、媒体库、空状态页
+  - 不直接覆盖核心画布、框选、拖拽、缩放、插件联动区域
+
+- Decision: 仓库内必须保存 Stitch 设计资产的映射关系
+
+  - 通过 `.stitch/screens.json` 记录 `surfaceId -> projectId -> screenId`
+  - 通过 `.stitch/DESIGN.md` 沉淀视觉系统、品牌语言与 prompt 约束
+  - 避免 Stitch screen 只存在于外部系统、无法被后续开发和维护复用
+
+- Decision: 设计结果进入代码前必须经过“结构转译”
+
+  - Stitch screen 的 HTML 与 screenshot 只作为视觉参考和结构蓝本
+  - 最终组件仍按 React + 现有工程模式手工实现
+  - 所有状态、事件、服务调用、数据依赖继续留在本地代码
+
+- Decision: 首批只跑通一个最小闭环，再逐步扩展
+
+  - 先选低风险单元，如 `CrashRecoveryDialog`
+  - 跑通完整流程后，再扩展到项目抽屉、设置面板、媒体库等
+
+## Proposed Repository Artifacts
+
+```txt
+.stitch/
+  DESIGN.md
+  screens.json
+  prompts/
+    crash-recovery-dialog.md
+    project-drawer.md
+    settings-panel.md
+  downloads/
+    <surface-id>/
+      screen.json
+      screenshot.png
+      design.html
+```
+
+### Artifact Roles
+
+- `DESIGN.md`
+  - 项目级视觉系统说明
+  - 颜色、字体、圆角、阴影、语气、信息密度等约束
+  - 作为 Stitch prompt 的上下文来源
+
+- `screens.json`
+  - 每个 surface 的唯一映射
+  - 示例：
+
+```json
+{
+  "crash-recovery-dialog": {
+    "projectId": "17192920079115887108",
+    "screenId": "49b0b7c5283f462d8fafd181b7cbaf5b",
+    "entry": "apps/web/src/app/CrashRecoveryDialog.tsx"
+  }
+}
+```
+
+- `prompts/*`
+  - 记录每个页面/模块送入 Stitch 的 prompt
+  - 保证后续编辑与再生成时上下文可追溯
+
+- `downloads/*`
+  - 保存从 MCP 拉回的 HTML / screenshot / metadata 快照
+  - 作为编码阶段的参考输入
+
+## Workflow
+
+1. 选择一个受边界约束的页面/模块
+2. 在 `.stitch/prompts/` 中整理 prompt，并结合 `.stitch/DESIGN.md`
+3. 使用 Stitch 生成或编辑 screen
+4. 将 `projectId` / `screenId` 固化到 `.stitch/screens.json`
+5. 通过 Stitch MCP 拉取 `get_screen`、设计系统与截图
+6. 按仓库规范将结果实现为 React 组件
+7. 完成后回写下载快照与必要的设计说明
+
+## Initial Candidate Surfaces
+
+- `apps/web/src/app/CrashRecoveryDialog.tsx`
+  - 优势：边界清晰、交互简单、适合先跑闭环
+- `packages/drawnix/src/components/project-drawer/*`
+  - 优势：信息层级明确，适合 Stitch 做布局与信息架构
+- `packages/drawnix/src/components/settings-dialog/*`
+  - 优势：表单和分组较多，适合先做视觉系统统一
+- `packages/drawnix/src/components/media-library/*`
+  - 优势：典型内容浏览 UI，适合做卡片、筛选、空状态设计
+
+## Risks / Trade-offs
+
+- 风险: 团队把 Stitch 结果误当成最终代码
+  - Mitigation: 在 spec 中明确“结构参考，不是生产代码”
+
+- 风险: screen 映射与代码实现脱节
+  - Mitigation: 每个 surface 必须在 `.stitch/screens.json` 中绑定入口文件
+
+- 风险: 过早接入复杂编辑器区域，增加返工成本
+  - Mitigation: 首批只选低风险外围页面
+
+- 风险: 外部 Stitch 项目变动无法追溯
+  - Mitigation: 在仓库中保存 prompt、screen 映射和下载快照
+
+## Open Questions
+
+- `.stitch/screens.json` 是否需要加入 `status` 字段，如 `concept / approved / implemented`
+- 下载快照是统一提交进仓库，还是仅作为本地辅助资产
+- 首批试点是否只选一个页面，还是并行推进多个低风险面板
--- a/openspec/changes/add-stitch-design-workflow/proposal.md
+++ b/openspec/changes/add-stitch-design-workflow/proposal.md
@@ -0,0 +1,54 @@
+# Change: 为 opentu 引入 Stitch 驱动的设计闭环工作流
+
+## Why
+
+当前 `opentu` 的前端页面与面板主要直接在代码中设计和实现，缺少一条稳定的“设计探索 -> 方案沉淀 -> 代码回收”的闭环。
+这会带来三个直接问题：
+
+- 新页面或复杂面板的视觉方案探索成本高，难以快速比较多个方向
+- 设计稿、实现代码、页面映射关系分散，后续复用和迭代成本高
+- 即使使用 Stitch，也缺少明确的仓库内落点，容易变成一次性的外部试验
+
+我们希望把 Stitch 接入为一个受控的设计工作流：
+- 先把适合的页面和面板送入 Stitch 进行方案设计
+- 再通过 MCP 将 screen 与 design system 信息拉回仓库
+- 最终由本地 React/业务层完成生产实现
+
+## What Changes
+
+- 引入仓库内的 Stitch 工作流约定，包括 `.stitch/` 目录、screen 映射文件与设计规范文档
+- 定义首批适合走 Stitch 的 UI 范围，优先覆盖外围页面、抽屉、弹窗、空状态页，不直接覆盖核心白板编辑器
+- 规范从 prompt 到 Stitch screen，再到 MCP 拉取与本地编码实现的标准流程
+- 明确代码与设计的边界：Stitch 负责视觉方案与结构参考，仓库代码仍然是交互行为与生产实现的唯一真源
+- 为后续将 Stitch screen 回收为 React 组件提供可追踪的映射关系
+
+## Impact
+
+- Affected specs:
+  - `stitch-design-workflow`
+- Affected code:
+  - `.stitch/*`
+  - `apps/web/src/app/*`
+  - `packages/drawnix/src/components/*`
+  - `packages/drawnix/src/contexts/*`
+  - `packages/drawnix/src/hooks/*`
+  - 未来首批接入页面对应的样式与组件文件
+
+## Initial Rollout Scope
+
+- 首批纳入 Stitch 设计闭环的页面/模块：
+  - `CrashRecoveryDialog`
+  - 设置面板 / 设置对话框
+  - 项目抽屉 / 项目列表
+  - 媒体库面板
+  - 空状态页 / 引导页
+
+- 首批明确不纳入 Stitch 主导设计的页面/模块：
+  - 核心白板画布
+  - 涉及拖拽、框选、缩放、插件联动的编辑器核心交互
+  - 多标签同步、任务队列、画布操作等逻辑驱动区域
+
+## Relationship To Existing Changes
+
+- 本变更与现有 provider / runtime model 相关提案无直接冲突
+- 本变更关注前端设计工作流与设计资产管理，不改变当前模型路由、任务执行和 SW 通信架构
--- a/openspec/changes/add-stitch-design-workflow/specs/stitch-design-workflow/spec.md
+++ b/openspec/changes/add-stitch-design-workflow/specs/stitch-design-workflow/spec.md
@@ -0,0 +1,61 @@
+## ADDED Requirements
+
+### Requirement: Maintain Stitch Design Artifacts In Repository
+
+The repository SHALL maintain persistent Stitch workflow artifacts for approved design surfaces, including project-level design context and screen mapping metadata.
+
+#### Scenario: Record a Stitch screen mapping for a repo surface
+- **GIVEN** a repo surface has been designed or updated in Stitch
+- **WHEN** that surface is accepted for implementation
+- **THEN** the repository SHALL store the corresponding `projectId` and `screenId`
+- **AND** SHALL associate that mapping with the local entry file or surface identifier
+
+#### Scenario: Persist project-level design context
+- **GIVEN** the project uses Stitch as part of its design workflow
+- **WHEN** a new surface is prepared for design generation or editing
+- **THEN** the workflow SHALL have access to a repository-local design context document
+- **AND** that document SHALL act as reusable prompt context across surfaces
+
+### Requirement: Restrict Stitch-First Design To Scoped UI Surfaces
+
+The system SHALL apply the Stitch-first workflow only to UI surfaces whose interaction boundaries are compatible with design-led iteration.
+
+#### Scenario: Allow a modal or panel into the Stitch workflow
+- **GIVEN** a UI surface is a dialog, drawer, settings panel, media browser, or empty state
+- **WHEN** the team selects surfaces for Stitch-based design work
+- **THEN** that surface SHALL be eligible for the Stitch workflow
+
+#### Scenario: Exclude the core editor surface from the initial Stitch rollout
+- **GIVEN** a UI surface depends on whiteboard editing, drag-and-drop, viewport transforms, selection state, or plugin-driven canvas behavior
+- **WHEN** the initial Stitch rollout scope is defined
+- **THEN** that surface SHALL be excluded from Stitch-first design ownership
+
+### Requirement: Use Stitch Outputs As Implementation References, Not Production UI
+
+Stitch-generated screens SHALL be used as implementation references for local components, rather than being embedded directly as the final production UI.
+
+#### Scenario: Recover a Stitch screen into a local React implementation
+- **GIVEN** a Stitch screen has been approved
+- **WHEN** the corresponding UI is implemented in the repo
+- **THEN** the team SHALL implement the production component in local application code
+- **AND** SHALL keep state, behavior, services, and event handling in the local codebase
+
+#### Scenario: Avoid direct runtime embedding of generated HTML
+- **GIVEN** a Stitch screen exposes HTML or screenshot assets
+- **WHEN** the UI is integrated into the application
+- **THEN** those assets SHALL be treated as design references or snapshots
+- **AND** SHALL not be the sole runtime implementation artifact for production use
+
+### Requirement: Support A Traceable Stitch Design Loop
+
+The Stitch workflow SHALL support a traceable loop from prompt authoring to screen generation, MCP retrieval, and local implementation.
+
+#### Scenario: Trace a surface from prompt to implementation
+- **GIVEN** a surface is being developed through the Stitch workflow
+- **WHEN** a teammate inspects the repository artifacts for that surface
+- **THEN** they SHALL be able to locate the prompt source, the Stitch screen mapping, and the local implementation entry
+
+#### Scenario: Reuse an existing Stitch surface during iteration
+- **GIVEN** a surface has already been created in Stitch and mapped in the repository
+- **WHEN** the team needs to revise that surface
+- **THEN** the workflow SHALL update the existing mapped screen instead of creating an untracked external design branch by default
--- a/openspec/changes/add-stitch-design-workflow/tasks.md
+++ b/openspec/changes/add-stitch-design-workflow/tasks.md
@@ -0,0 +1,29 @@
+## 1. Workflow Definition
+
+- [ ] 1.1 定义 `opentu` 中哪些 UI 适合走 Stitch，哪些 UI 必须继续以代码驱动为主
+- [ ] 1.2 定义从 prompt 到 Stitch screen，再到 MCP 拉取与编码实现的标准闭环
+- [ ] 1.3 明确设计稿、screen 映射、代码实现之间的责任边界
+
+## 2. Repository Artifacts
+
+- [ ] 2.1 建立 `.stitch/` 目录结构与命名约定
+- [ ] 2.2 定义 screen 映射文件格式，用于记录 `repo surface -> projectId -> screenId`
+- [ ] 2.3 定义 `.stitch/DESIGN.md` 的职责，用于沉淀项目视觉系统与 prompt 上下文
+
+## 3. Initial Rollout Surfaces
+
+- [ ] 3.1 选择首批 3 到 5 个低风险页面/模块作为 Stitch 试点
+- [ ] 3.2 为每个试点页面记录目标、边界、依赖状态与实现入口文件
+- [ ] 3.3 明确每个试点页面的 Stitch prompt 与回收编码策略
+
+## 4. Design Retrieval And Implementation Rules
+
+- [ ] 4.1 约定如何从 Stitch MCP 拉取 `screen`, `htmlCode`, `screenshot`, `designSystem`
+- [ ] 4.2 约定如何将 Stitch 结果转译为 React 组件，而不是直接嵌入原始 HTML
+- [ ] 4.3 约定如何在实现完成后回写或更新 screen 映射与设计文档
+
+## 5. Verification
+
+- [ ] 5.1 用一个真实页面跑通完整闭环：需求 -> Stitch 设计 -> MCP 拉取 -> 本地实现
+- [ ] 5.2 验证 `.stitch` 资产、screen 映射与实现组件之间可追踪
+- [ ] 5.3 验证试点流程不会干扰核心编辑器功能开发