ptp-transplant

Prototype to Production Transplant：一个协助 AI Agent 把已确认原型接到正式应用上的 Skill 项目。它针对“原型好看、后端已有、但反复接成另一套页面”的问题：在取得可读取的原型源码后把原型作为页面可见结构的来源，把正式 contracts、API、权限、URL 与状态机作为事实和行为来源，把用户实际验收作为完成条件。仅能看到原型而无源码时，不把视觉重建冒充源级移植。

目前方法仍待不同规模的真实项目验证；文档不保证任何 npm 发布状态。仓库根目录不属于 Agent Hub；原项目文件不由这里修改。

适用场景

• 已有可取得源码的页面原型，正式应用也有可复用的后端或行为资产，需要把两者接起来；静态展示页也可做结构移植并明确无行为接线。
• 旧 UI 被判废，要保留正式命令、错误语义与测试，但不希望新视图从旧壳自由生长。
• 新项目的第一版产品化：旧视图和旧测试可以没有，仍可用本 Skill 对齐目标和接线。
• 项目很小：一条命令就能运行页面时，无需为了遵循 Skill 搭数据库、worker 或生成四份长文档。

不适用于没有页面原型的从零设计，或只是换主题、改几处 CSS、无需对照用户签收原型的任务。

使用方法

安装与试用

本仓库根目录含 Skill 本体（SKILL.md + reference/ + templates/）及安装器等开发文件。安装器只把这三个 payload 放进 Agent 的 Skill 发现路径：

# 安装到当前项目的 .agents/skills/ptp-transplant（默认）
npx github:ktdhhc/ptp-transplant

# 安装到用户级 ~/.agents/skills/ptp-transplant（所有项目可用）
npx github:ktdhhc/ptp-transplant --global

# 先看会写到哪里，不落盘
npx github:ktdhhc/ptp-transplant --dry-run

选项：--global/-g 用户级安装、--dir <path> 指定目标、--force/-f 覆盖已存在、--dry-run 预演、--help 说明。目标目录必须名为 ptp-transplant；--force 只覆盖经识别的本 Skill 既有安装，不会替换其他目录。安装后重启该项目的 Agent 会话，Skill 才会被发现。

以上示例从 GitHub 仓库取安装器，不代表 npm 包已发布；需要 npm 包名安装时先核实发布状态。也可以不用安装器：建立 <项目>/.agents/skills/ptp-transplant/（或 ~/.agents/skills/ptp-transplant/），仅复制 SKILL.md、reference/、templates/ 三项进去，不要把整个仓库、安装器、测试或其他开发文件当作 Skill payload。

用户可以说“把签收的 demo 页面接到正式 Web，后端/API 已有，按 ptp-transplant 做”，或在支持 slash command 的宿主里显式调用 /ptp-transplant。Skill 应先核对 grilling、to-tickets、browser-use 和截图能力；缺失时说明影响并询问是否继续，而非静默冒充完整验收。to-tickets 在部分宿主只接受用户显式触发，需由用户发起 /to-tickets。

工作方式

用户向大流程：对齐目标和签收版本 → 立页面票与边界 → 用户在正式页面操作并签收。

工程向小流程：核实原型源码与权限、枚举区域与正式行为 → 建立一份“移植底账” → 从可读原型源码复制成功态骨架并验结构（占位不算行为完成）→ 按实际区域接正式事实（静态页可无此步）→ 统一整页复核及实际交互复演；所有写入副作用先隔离并获授权。缺源码则阻塞源级移植，请用户选择提供源码或另立视觉重建目标。

原型与正式要求冲突时，有编辑许可才在隔离的 demo 缺陷分支做可看的目标态；只读原型则制作独立可视提案，记录“原版本 + 获准提案版本”，不宣称已改原型源码。用户确认目标后更新该页面的目标依据与正式页面。这是贯穿流程的变更控制，不是允许 agent 自行扩大页面的借口。

文件导航

| 路径 | 作用 | 何时读 | |---|---|---| | SKILL.md | 触发、能力检查、用户向大流程与底线 | 触发时 | | construction-plan.md | 工程规划：工件、骨架门、接线切片与收口 | 每张页面票开工时 | | construction-discipline.md | 工程约束：不降级、不连续自证、偏离与故障退路 | 施工与声明通过时反复核对 | | failure-modes.md | 两次真实实施的失败模式 | 排障与评审时按需读 | | templates/ | 原型区域、正式行为、移植底账、条件性测试分诊 | 产出任务工件时按需复制 | | 本地 docs/ | 背景文章与三份研究笔记 | 了解缘起时（不随仓库发布） |

最小输入与产出

输入最好包括：目标页面及原型固定版本、源码可得性与读／改权限、已有正式行为/后端入口、用户特别批准或拒绝的可见偏离、可运行方式及写入授权。缺其中一项并非一律停工：小项目有可读原型源码即可先做骨架结构；正式行为显式缺失时问清本轮到底要接哪些行为，纯静态页可明确无行为；缺浏览器时可做准备或可由测试支持的代码工作，但实际交互门未验证；缺截图时视觉门未验证，不能声称通过。

产出以一张页面票、一份移植底账、一套可运行正式页面及可追溯证据为主。四个模板不是强制四个文件：无旧 UI 测试时不创建测试分诊；工件很短时可放进同一任务票。把区域映射与交互复演放在同一份底账，避免多份状态互相矛盾。

开发状态与试用建议

• 已建立 Skill 主文件、工程规划、工程约束、四个可裁剪模板和失败案例参考。
• 尚未用 2–3 个不同规模的真实项目试跑；不要把“文件已写完”误认为 Skill 已验证。
• 试用宜包括：①有可读源码、只有静态 demo 和一行启动命令的小项目；②已有 API/URL/写命令的大页面；③只读或无源码原型、缺 browser-use 或 to-tickets 的能力降级情形。记录触发是否正确、是否制造不必要工件、是否遗漏整页结构、遇截图故障是否及时向用户升级。
• 仓库的 Git 状态与远端以实际检出为准；示例 GitHub 安装命令不构成 npm 发布或任何版本发布的保证。