existing-project-migration

现有项目迁移

核心理念

每次压缩后、继续工作前，都要重新阅读此 SKILL.md。不要认为对话记忆足够可靠。

此技能用于技术栈迁移，而非产品重新设计。

• 客户已经有一个应用。
• 工作是将该应用重组为 Customware 技术栈。
• 源产品的路由、工作流、标签、布局框架、页面分区、分区顺序、视觉风格和样式都应作为忠实于源产品的移植内容保留下来。默认预期是不有意改变面向用户的 UI 或 UX。
• 运行时技术栈必须更换为准备好的 Customware 技术栈，该技术栈由 template-be-setup 构建，并合并必需的 client-only-spa 规则。

不要将此任务视为从头构建应用、重新诠释领域，或将产品简化为更小的通用仪表板的机会。 不要沿用任何先前迁移的预期。此技能必须适用于客户上传的任意应用。每次都要根据当前导入的源文件重新确定需要保留的内容。 熟悉源应用的客户应感觉自己是在新技术栈上使用同一个应用，而不是使用一个重制版。 如果确实受到技术栈限制、缺少源文件或源代码缺陷影响而无法完全保持一致，应尽量缩小差异，并将其明确记录为具名偏差。

源文件权威性

迁移以导入的文件为准。

优先级：

1. projects.zip 中的 .import/project/ 是产品行为、路由、UI、工作流、集成和业务逻辑的主要依据。
2. database.zip 中的 .import/database/ 是持久化实体、架构推断以及存在 CSV 行时种子数据的主要依据。
3. domain.zip 中的 .import/domain/ 和 .import/domain-source.txt 仅作为辅助背景信息。
4. .tasks/domain.md，以及组织名称、组织描述、徽标、颜色和品牌背景，仅作为低优先级的呈现背景信息。

不要让组织或公司的相关知识，或 .tasks/domain.md 重新定义导入产品的领域、路由、工作流、架构或产品定位。此迁移有意不将领域技能作为产品权威依据。 即使存在 .tasks/domain.md，在迁移过程中做产品定义决策时，也应基本忽略它。真正的事实来源是 .import/project/ 中导入的代码库，以及 .import/database/ 中导入的数据库文件。仅在领域材料有助于澄清次要呈现背景时使用，且绝不能让它的优先级高于源代码或源数据。

固定目标技术栈

迁移至准备好的 Customware 全栈目标：

• Vite
• React Router
• TypeScript
• Zod
• Node
• Hono
• tRPC
• 通过 better-sqlite3 使用 SQLite
• Drizzle ORM 和迁移

不要保留上传的源应用原有的运行时技术栈。

必需的阶段参考文件

开始工作前，阅读当前任务对应的准确文件。

• Migration build
  • .agents/skills/existing-project-migration/references/phase-1/overview.md
  • .agents/skills/existing-project-migration/references/phase-1/artifacts.md
  • .agents/skills/existing-project-migration/references/phase-1/grading.md
• Migration verify
  • .agents/skills/existing-project-migration/references/phase-2/overview.md
  • .agents/skills/existing-project-migration/references/phase-2/artifacts.md
  • .agents/skills/existing-project-migration/references/phase-2/grading.md

如果任务描述不清楚，先阅读两个阶段的概述文件，确定当前所处阶段，再加载对应的产物和评分参考文件。

关键迁移不变量

以下是硬性规则。

• 这是一次技术栈迁移。保留源产品，替换运行时基础。
• 保留导入应用中用户可见的路由映射、路由路径、导航标签、页面层级、标题、页面区块、区块顺序、区块样式、控件界面、工作流、排版、主题令牌和 Logo 用法。默认假设：有意的用户可见改动为零。
• 保留源应用中实际的屏幕类型和具体页面契约。如果源页面是日历，就以日历为核心。如果是密集型表格工作区，就保留该结构。如果是真正的配置表单，就保留相同的表单界面。不要仅仅因为业务领域相似，就把一种屏幕类型替换成另一种。
• 将导入的前端视为视觉和信息架构的权威，并将源路由／页面文件视为迁移目标。在确定 UI 方向之前，请先阅读当前使用的路由器／启动入口、布局／导航文件、主题／根 CSS 文件、关键资源和代表性页面文件。
• 直接移植源页面结构和样式令牌。不要把源 UI 改写成新的摘要、辅助文字、说明面板或通用产品文案。
• 在任何交互验证之前，直接对照源前端代码、迁移后的代码以及任何可用的源截图，进行迁移前的保真度审查。确认共享外壳以及每个源中可见的屏幕都保留了预期布局区块、具名区块、区块顺序、标题、标签、控件、操作、表格、图表、表单、选项卡和样式方向，然后再打开浏览器。
• 对每个源中可见的屏幕，在实现或评分之前提取精确的屏幕契约。该契约必须包含从源应用中提取的准确按钮标签、选项卡标签、筛选器标签、区块标题、表格列、关键操作、具名区块和区块顺序。
• 在交互式 QA 之前，代码中可见的遗漏即视为失败。如果源代码清楚表明存在侧边栏、导航区块、页眉、选项卡栏、表头、筛选行、表单区块、图表区块、操作组或其他可见区块，而迁移后的代码没有保留，那么即使页面能够正常渲染，这一阶段仍未完成。
• 如果提取出的任何精确契约项缺失、改名、顺序变更、样式改到面目全非，或在没有明确阻碍因素的情况下被其他界面替代，那么该评分轮次不通过。将这些未通过的精确契约项作为下一轮必须修复的队列，并持续迭代，直到屏幕通过。
• 如果用户确实无法避免会注意到的 UI 差异，须将其控制在最低限度，并明确记录在 migration-plan.json、migration-review.md 和 migration-open-gaps.md 中。未记录的偏差即为失败。
• 不要编造诸如 Imported App Migration、Migration slice 或类似框架的迁移主题文案。
• 除非源应用本身使用了相关措辞，任何面向用户的文案都不得提及 imported、migrated、source、preserved、phase、CSV、seed、staging、readiness、review，或任何同类的来源叙述。
• 不要仅仅因为 CSV 导出数据只覆盖了数据模型的一部分，就将导入的应用缩减为狭窄的垂直切片。
• 不要用通用主视觉卡片、占位仪表板、填充文案、摘要卡片、就绪状态面板或通用审核／状态外壳替换源中可见的页面。
• 交互验证始终从最终用户的角度进行。如果存在实际的审核或预览主机，则从该主机上用户可见的第一个页面开始；通常是在未登录状态下访问 /。
• 交互验证必须证明可见内容一致，而不只是证明 DOM 存在。只有当预期的外壳、布局区块和关键控件在屏幕上可见地渲染，并且至少有一个基本的页面原生操作可用时，才算覆盖该路由。隐藏文本、脱离页面的 UI 或仅附加到 DOM 的节点均不算成功。
• 第 1 阶段验证是全面的交互式 QA，而不是编写广泛的自动化测试套件。以用户视角访问每个可用的迁移后页面路由，在每个路由上至少执行一个基本的页面原生操作，并覆盖常见流程，例如登录、退出、导航、搜索、筛选、选项卡、表单、详情视图，以及存在相应界面时的集成或配置操作。
• 自动化单元测试和端到端测试套件主要属于第 2 阶段。第 1 阶段只有在迁移或交互式 QA 受阻时才可添加或修复测试，但第 1 阶段的签核取决于全面的交互证据，而非自动化测试套件的覆盖广度。
• 如果存在审核或预览 URL，仅在 localhost 或调试端口上进行验证不足以通过签核。
• 首个页面空白、登录页面空白、预置登录失败、应用内首次导航失败、控制台出现致命错误，或水合／运行时启动错误，均自动判定为失败。
• 不要为了让迁移看起来成功而保留旧运行时、向后兼容处理程序或额外的验证器服务。
• 如果模板演示页面、占位文案和仅适用于模板的测试不再符合导入的产品，就应移除。
• 如有 .import/database/ 中的 CSV 行数据，则以其作为种子数据的权威来源。
• 使用以下由 Agent 维护的审核文档作为执行标准。如果评分不通过或仍存在一般性偏差未解决，该阶段就仍未完成。
• 仅根据当前导入的应用评估保真度。不要让先前迁移的经验变成后续迁移中未明示的产品要求。

必需的强制执行工件

迁移期间，这些文件是必需的质量门禁：

• .import/migration-plan.json
• .import/migration-checklist.md
• .import/migration-review.md
• .import/migration-open-gaps.md

直接使用这些模板：

• .agents/skills/existing-project-migration/assets/templates/migration-plan.json
• .agents/skills/existing-project-migration/assets/templates/migration-checklist.md
• .agents/skills/existing-project-migration/assets/templates/migration-review.md
• .agents/skills/existing-project-migration/assets/templates/migration-open-gaps.md

规则：

• Migration build 仅在深入了解源项目后，才会创建任何缺失的工件。
• 如果在验证开始时缺少任何必需工件，Migration verify 将失败。
• 每次有实质意义的实现或验证之后，都要更新 migration-review.md 和 migration-open-gaps.md。
• 评审和未解决问题台账必须逐一跟踪源项目中可见的每个屏幕，并记录任何必要的共享 shell 或运行时行，以提供上下文。
• 不得用含糊的文字说明替换模板中的台账表格。
• 如果尚未记录对抗性检查，且该检查确实未发现任何阻塞性偏差，则首次正式评分不得宣称没有未解决问题。
• 如果任何关键评分项未通过、未达到分数门槛，或 migration-open-gaps.md 中仍有一般性迁移偏差，则任务尚未完成。

阶段模型

• Migration build 是第 1 阶段。
  • 深入收集源项目资料
  • 迁移计划和检查清单
  • 合并模板
  • 基于源项目生成架构、路由、页面和工作流
  • 基于源项目翻译 UI，逐条路由确保与源屏幕一致
  • 在浏览器 QA 之前，对照源代码和屏幕截图进行交互前的对抗式自评
  • 从用户视角，对所有可用的已迁移页面路由进行全面交互验证
  • 首次获得通过的迁移评分，且不存在尚未解决的用户可见差异
• Migration verify 是第 2 阶段。
  • 重新加载第 1 阶段产物
  • 重新加载第 1 阶段的交互式 QA 证据
  • 修复 verify 问题后，从用户视角进行简短的合理性复查
  • 使用全新数据库进行运行时验证
  • 编写或修复单元测试
  • 修复或扩展 Playwright 端到端覆盖
  • 最终获得通过的迁移评分
  • 最后一步清理 .import/、Playwright 输出和仅用于迁移的临时产物

两个阶段都必须持续迭代，直到分数达到阈值、所有关键项都通过，且不存在尚未解决的一般差距。 不要只运行几次评分，发现仍未通过就停止。评分的目的就是促使更多迭代。持续修复并重新评分，直到结果超过通过标准且分数足够高，达到较高的通过水平，而不是勉强过关。

第 1 阶段以交互测试为主。第 2 阶段以自动化测试为主。 第 1 阶段应交付忠实于源项目的应用，以及全面的用户视角路由覆盖证据。 第 2 阶段应将这些证据转化为持久的单元测试和端到端测试覆盖，只进行轻量的交互式合理性复查，然后确保代码仓库保持干净。

UI 的精确保留由第 1 阶段负责。不要把重要的屏幕一致性工作推迟到第 2 阶段。到第 1 阶段结束时，迁移后的应用应已在外观和行为上与原应用一致，仅运行时有所替换。 由于 Agent 可以直接读取源前端代码，应将原始 UI 实现视为翻译输入，而非灵感来源。应尽可能直接地将路由级组合、命名页面区块、区块顺序、标签、操作、筛选器、表单、表格、图表、空状态和样式 token 移植到新技术栈中。 仅在视觉上接近、仅属于同一业务领域，或通过迁移说明或来源说明文案进行解释的屏幕，都不合格。 不要等到浏览器测试时才发现代码已经揭示的基本结构差异。如果源应用明确包含持久侧边栏、导航区块、页眉区块、标签栏、筛选栏、完整表格区块、表头带、表单区块或其他主要可见界面，应在交互测试前确认迁移后的代码仍以大致相同的布局包含这些内容。 每个屏幕的评分都必须具体，不能凭印象判断。逐项比较迁移后的屏幕与提取出的精确要求，发现不匹配就判定本轮不通过，并进行修复和重新评分，直到屏幕通过。

不可妥协事项

• 保持迁移由 zip 驱动。
• 组织上下文仅限于展示上下文，不得作为产品权威上下文。
• 运行时必须使用固定的 Customware 技术栈。
• 合并 client-only-spa 的 app/ 时，保留 app/lib/trpc-provider.tsx 和 app/utils/error-logger.ts。
• 任何已发布的路由或页面都不得包含与迁移相关的叙述或来源说明。
• 如果真实的审核或预览应用启动后显示空白屏幕，或在用户能够访问登录页或登录后的首个页面之前崩溃，则不得通过任何阶段。
• 不得仅凭附件检查或隐藏元素检查通过任何阶段。验证证据必须证明预期 UI 已清晰呈现，并且从用户视角来看可正常使用。
• 除非已准备好的工作区中包含获准的克隆，否则不要在工作区外搜索其他模板说明。
• 在第 1 阶段以及第 2 阶段验证期间，保留 .import/ 和其他临时迁移证据；随后在第 2 阶段的最终清理步骤中将其移除，除非任务明确要求永久保留。
• 若迁移质量不足，应指出具体阻碍，而不是自行批准。