fork-first-methodology

Fork-First 开发规范（RULE-FORK-FIRST）

触发条件：任何「基于 X 项目」「在 X 的基础上」「fork X 然后」「复用 X 的核心」类描述的开发任务。

---

核心原则

这不是从头开发。修改量应该最小，已有的东西不要重写。

从头开发和 Fork-First 的本质区别：

维度	从头开发	Fork-First
起点	空项目	已有能跑通的完整系统
目标	实现全部功能	只改需要改的部分
评价标准	功能完整性	Delta（变更量）最小
最大风险	遗漏功能	重写已有的东西

---

强制执行步骤（不可跳过）

Step 1：先完整跑通基础项目（不改任何东西）

# 正确做法：
cp -r reference/repos/openclaw/ 项目群/my-project/
cd my-project
npm install
# 按原项目文档配置
# 验证：所有原有功能正常工作

禁止：在基础项目跑通之前开始任何改动。

Step 2：理解「改动边界」（前端 vs 后端 vs API）

必须明确回答：

□ 我要修改的是哪一层？（前端 / 后端 / 数据层 / 配置）
□ 我保留不变的是哪一层？
□ 两层之间的接口是什么？（REST API / WebSocket 协议 / 函数签名）
□ 接口规范在哪里有文档？（源码中的哪个文件）

Step 3：做最小侵入修改

原则：
✅ 替换整个前端目录（ui/ → react-ui/），后端一行不改
✅ 新增配置项，保持向后兼容
✅ 在现有扩展点注册新插件/工具

❌ 重写已有的核心模块（「因为想更了解」「想用不同技术栈」）
❌ 自制一套已有功能的替代品（「更简洁」「更符合我们的需求」）
❌ 抛弃已有的 API 层，另起炉灶

Step 4：每一步都有验证

修改前：记录基础项目的行为（截图/测试/API 响应）
修改后：对比验证行为一致
每个 commit：都要能独立跑通，不允许「等后面修复」

---

诊断清单（开始 fork-based 开发前必做）

在开始任何修改之前，必须回答：

□ 基础项目是否已经在本地跑通？（服务启动 + 核心功能可用）
□ 是否已阅读基础项目的架构文档（README/ARCHITECTURE.md）？
□ 是否已确认改动边界（改哪里 / 不改哪里）？
□ 是否已找到前后端之间的 API 接口定义？
□ 是否评估过「只替换前端」是否足够满足需求？

如果上述任何一项回答「否」，必须先完成该项，再继续。

---

架构文档要求

所有 Fork-First 项目的技术架构文档必须包含：

## 基础项目信息
- 上游项目：[名称 + URL]
- 基准版本：[commit hash 或版本号]
- 许可证：[MIT/Apache 等]

## 修改边界声明
- 保留不改的部分：[列举]
- 我们替换的部分：[列举]  
- 我们新增的部分：[列举]

## 前后端接口协议
- 协议类型：[WebSocket v3 / REST / gRPC / ...]
- 协议定义文件：[路径]
- 我们的实现需遵循：[链接或说明]

---

反模式（已发生的教训）

以下是曾经犯过的错误，未来不允许重复：

❌ tashan-forge 案例（2026-03-22）：
  - 目标：给 OpenClaw 换一个 React 前端
  - 实际做法：
    × 没有 fork OpenClaw，而是从零建了新项目
    × 自己实现了 Hono Server + Bus + SSE（OpenClaw 已有）
    × 自己实现了 config.ts（OpenClaw 已有完整配置系统）
    × 只使用了 pi-coding-agent 的 5 个导出（完整系统的 ~5%）
  - 结果：用 ~1000 行代码重复实现了 OpenClaw 已有的后端功能
  - 正确做法：
    ✅ fork reference/openclaw-main 整体复制
    ✅ npm install，配 API Key，跑通
    ✅ 只替换 ui/ 目录（Lit → React）
    ✅ 新前端接 OpenClaw 现有的 WebSocket v3 协议

---

变更记录

2026-03-22 — 初始创建