@c-d-cc/reap 0.4.0 → 0.5.0

package/README.zh-CN.md

@@ -1,3 +1,5 @@
+> [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
+
 <p align="center">
   <img src="media/logo.png" alt="REAP" width="80" height="80" />
 </p>
@@ -9,8 +11,6 @@
   AI与人类通过迭代Generation来进化软件的开发管线。
 </p>
 
-> [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
-
 <table align="center">
 <tr>
 <td align="center"><strong>Genome</strong><br><sub>设计与知识</sub></td>
@@ -23,6 +23,22 @@
 
 REAP定义应用程序的遗传信息（Genome），为每个世代设定目标进行实现，并将过程中发现的Genome缺陷反馈到后续阶段。随着世代的积累，Genome不断进化，Source Code（Civilization）持续成长。
 
+## 目录
+
+- [为什么选择REAP？](#为什么选择reap)
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [生命周期](#生命周期)
+- [核心概念](#核心概念)
+- [分布式工作流 — 并行开发](#分布式工作流--并行开发)
+- [CLI命令](#cli命令)
+- [代理集成](#代理集成)
+- [`reap init`后的项目结构](#reap-init后的项目结构)
+- [谱系压缩（Lineage Compression）](#谱系压缩lineage-compression)
+- [进化流程（Evolution Flow）](#进化流程evolution-flow)
+- [预设（Presets）](#预设presets)
+- [入口模式（Entry Modes）](#入口模式entry-modes)
+
 ## 为什么选择REAP？
 
 在使用AI代理进行开发时，你是否遇到过这些问题？
@@ -31,6 +47,7 @@ REAP定义应用程序的遗传信息（Genome），为每个世代设定目标
 - **分散开发** — 没有明确目标地到处修改代码
 - **设计与代码脱节** — 文档和代码随着时间推移越来越不一致
 - **遗忘的教训** — 辛苦获得的经验教训无法带到下一次工作中
+- **协作混乱** — 多个开发者或代理并行工作时冲突频发，合并变成噩梦
 
 REAP通过**基于世代的进化模型**解决这些问题：
 
@@ -39,6 +56,7 @@ REAP通过**基于世代的进化模型**解决这些问题：
 - 实现过程中发现的设计问题记录在backlog中，在Completion时反映
 - 回顾（Completion）中提取的教训积累在Genome中
 - 跨世代自动检测重复的手动操作，经用户确认后生成Hook
+- 跨分支的并行工作通过genome-first合并工作流进行协调 — 先解决设计冲突，再解决代码冲突
 
 ## 安装
 
@@ -146,6 +164,55 @@ Objective → Planning → Implementation ⟷ Validation → Completion
 └── lineage/       # 已完成世代的归档
 ```
 
+## 分布式工作流 — 并行开发
+
+> **⚠ 早期阶段** — 分布式工作流需要进一步测试。请在生产环境中谨慎使用。我们正在收集反馈 — [提交Issue](https://github.com/c-d-cc/reap/issues)。
+
+REAP支持多个开发者或AI代理在同一项目中并行工作的分布式协作，无需中央服务器，Git是唯一的传输层。
+
+### 工作原理
+
+```
+Machine A: branch-a — gen-046-a (authentication)    → /reap.push
+Machine B: branch-b — gen-046-b (search)            → /reap.push
+
+Machine A:
+  /reap.pull branch-b   → Fetch + 运行完整的合并Generation生命周期
+```
+
+每台机器在自己的分支和Generation上独立工作。需要合并时，REAP通过**genome-first**策略来协调（[了解更多](https://reap.cc/docs/merge-generation)）：
+
+1. **Detect** — 通过git ref扫描远程分支的genome和lineage，识别分歧点
+2. **Mate** — 首先解决Genome冲突（由人工判断）
+3. **Merge** — 以确定的Genome为基准合并源代码（`git merge --no-commit`）
+4. **Sync** — AI比较Genome和源代码的一致性；发现不一致时由用户确认
+5. **Validation** — 运行机械化测试（bun test、tsc、build）— 与正常Generation相同
+6. **Completion** — 提交合并结果并归档
+
+### 分布式工作流斜杠命令
+
+所有分布式操作通过AI代理执行：
+
+```bash
+/reap.pull <branch>        # Fetch + 运行完整合并Generation（分布式 /reap.evolve）
+/reap.merge <branch>       # 本地分支完整合并Generation（无需fetch）
+/reap.push                 # 验证REAP状态 + push当前分支
+/reap.merge.start          # 启动合并Generation（用于逐步控制）
+/reap.merge.detect         # 分析分歧
+/reap.merge.mate           # 解决Genome冲突
+/reap.merge.merge          # 合并源代码
+/reap.merge.sync           # 验证Genome-源代码一致性
+/reap.merge.validation     # 运行机械化测试（bun test、tsc、build）
+/reap.merge.evolve         # 从当前阶段运行合并生命周期
+```
+
+### 核心原则
+
+- **Opt-in** — `git pull`/`push`始终正常工作。REAP命令是附加的。
+- **Genome-first** — 在源代码合并之前先解决Genome冲突。就像先修宪再修法。
+- **无需服务器** — 一切基于本地 + Git，无需外部服务。
+- **DAG lineage** — 每个世代通过基于哈希的ID（`gen-046-a3f8c2`）引用其父代，形成有向无环图，天然支持并行工作。
+
 ## CLI命令
 
 | 命令 | 说明 |
@@ -187,6 +254,16 @@ REAP通过斜杠命令和会话钩子与AI代理集成。当前支持的代理
 | `/reap.help` | 24+主题的上下文AI帮助（workflow, genome, backlog, strict, agents, hooks, config, evolve, regression, author及所有命令名） |
 | `/reap.update` | 检查REAP更新并升级到最新版本 |
 | **`/reap.evolve`** | **从头到尾运行一个完整的Generation（推荐）** |
+| **`/reap.pull <branch>`** | **Fetch + 运行完整合并Generation（分布式 `/reap.evolve`）** |
+| **`/reap.merge <branch>`** | **本地分支完整合并Generation（无需fetch）** |
+| `/reap.push` | 验证REAP状态并push当前分支 |
+| `/reap.merge.start` | 启动合并Generation以整合分歧分支 |
+| `/reap.merge.detect` | 分析分支间的分歧 |
+| `/reap.merge.mate` | 在源代码合并前解决Genome冲突 |
+| `/reap.merge.merge` | 以解决后的Genome为指导合并源代码 |
+| `/reap.merge.sync` | 验证Genome与源代码的一致性（AI比较，用户确认） |
+| `/reap.merge.validation` | 运行机械化测试（bun test、tsc、build） |
+| **`/reap.merge.evolve`** | **自动运行完整的合并生命周期** |
 
 ### SessionStart Hook
 
@@ -202,24 +279,30 @@ REAP通过斜杠命令和会话钩子与AI代理集成。当前支持的代理
 
 ### Strict模式
 
-在`.reap/config.yml`中设置`strict: true`可以限制AI代理在REAP工作流之外修改代码：
+Strict模式控制AI代理被允许执行的操作。支持两个细粒度选项：
 
 ```yaml
 # .reap/config.yml
-strict: true      # 默认：false
-language: korean  # 产出物和交互的语言
-autoUpdate: true  # 会话开始时自动更新
-agents:           # 检测到的代理（由reap init/update管理）
-  - claude-code
-  - opencode
+strict: true              # 简写：同时启用edit和merge
+
+# 或细粒度控制：
+strict:
+  edit: true              # 将代码修改限制在REAP生命周期内
+  merge: false            # 限制直接的git pull/push/merge
 ```
 
+**`strict.edit`** — 代码修改控制：
+
 | 情境 | 行为 |
 |------|------|
 | 无活跃Generation / 非实现阶段 | 代码修改完全阻止 |
 | Implementation阶段 | 仅允许`02-planning.md`范围内的修改 |
 | 逃生舱 | 用户明确请求"override"或"bypass strict"时允许 |
 
+**`strict.merge`** — Git命令控制：启用后，直接使用`git pull`/`push`/`merge`将被限制。代理会引导用户使用`/reap.pull`、`/reap.push`、`/reap.merge`。
+
+两者默认都禁用。`strict: true`同时启用两者。
+
 Strict模式默认禁用（`strict: false`）。
 
 ### REAP Hooks
@@ -253,6 +336,9 @@ order: 10                     # 执行顺序（数值越小越先执行）
 | `onStageTransition` | `/reap.next`前进到下一阶段后 |
 | `onGenerationComplete` | `/reap.next`归档已完成的Generation后 |
 | `onRegression` | `/reap.back`回到前一阶段后 |
+| `onMergeStart` | `/reap.merge.start`创建合并Generation后 |
+| `onGenomeResolved` | 合并过程中Genome冲突解决完成后 |
+| `onMergeComplete` | 合并Generation归档后 |
 
 Hook由AI代理在项目根目录中执行。`onGenerationComplete` Hook包含自动版本号升级判断 — patch级别自动应用，minor/major级别需要用户确认。