x

2026-09-20 00:28:52 +08:00
parent d33d1932b6
commit b7640e9be4
34 changed files with 2026 additions and 302 deletions
@@ -324,3 +324,66 @@ CI runs the same `npm run check` (plus Vitest) — commits that fail will not me
 - Leave debug `console.log` statements in code
 - Use raw color values in CSS — always use CSS custom properties
 - Commit without passing all linters (`npm run check` for the frontend; `cargo fmt` + `cargo clippy` for the backend)
+
+# 本地 fork 维护规则（Local fork rules）
+
+> 本节是仅本地追加的内容，不属于上游 OxiCloud。与上游合并时，若本节之外的部分发生冲突，
+> 以上游为准；本节始终保留在文件末尾以减少冲突面。
+
+## 背景
+
+本仓库是开源项目 OxiCloud 的本地副本，上游会持续更新。本地修改必须
+**可追溯、可合并**：任何时候都要能知道"我们改了什么"，以便与上游主分支合并。
+
+## 规则 1：计划与进度必须记录在 `status.md`
+
+- 每次接到非琐碎任务，**开始前**先在 `status.md` 顶部（"进行中"区域）写下计划。
+- `status.md` 条目格式（每条任务一个区块）：
+
+```markdown
+### [YYYY-MM-DD] 任务标题
+- **状态**: 进行中 / 已完成 / 已放弃（写明原因）
+- **计划**: 要做什么、分几步
+- **改动文件**: 列出修改/新增的上游文件（相对路径）+ 一句话说明
+- **仅本地文件**: 新增的不属于上游的文件（合并时无需处理）
+- **上游冲突风险**: 高 / 中 / 低，以及可能与上游哪些文件冲突
+```
+
+- 状态只允许进行中/已完成/已放弃三种；完成的任务移入"已完成"区域，保留记录不删除。
+
+## 规则 2：每次修改后立即更新 `status.md`
+
+- **不需要用户提醒**。任何一次代码/文档修改完成后，agent 必须同步更新
+  `status.md` 中对应条目的状态、改动文件列表和冲突风险。
+- 即使任务中途被打断，也要把当前进度写清（做到哪一步、剩下什么），保证
+  任何 agent（或人）读了 `status.md` 就能接手。
+
+## 规则 3：与上游主分支合并
+
+- **小步提交**：一个任务一个 commit（或少量 commit），commit message 说清楚改了什么。
+  不要把多天的工作堆成一个巨型 commit，否则合并时无法选择性丢弃。
+- **少改上游文件**：能用新增文件解决的（新组件、新模块、新 endpoint）就不要改上游现有文件；
+  必须改时尽量小而集中，并在 `status.md` 的"上游冲突风险"里注明。
+  **`AGENTS.md` 本身也因此只允许在文件末尾追加内容，不得改动上游已有的章节。**
+- **不改无关格式**：不要顺手重排上游代码、改无关 import 顺序——纯噪音，制造冲突。
+- 合并上游的流程：
+
+```bash
+git remote add upstream <上游仓库地址>   # 只需配置一次
+git fetch upstream
+git merge upstream/main                  # 或 rebase，按团队习惯；首次建议 merge
+# 解决冲突时：先读 status.md 的"改动文件"列表，逐个文件核对本地意图
+git status                               # 确认没有遗漏的冲突标记
+cargo fmt --all && cargo clippy --all-features --all-targets -- -D warnings
+just test
+```
+
+- 合并完成后，在 `status.md` 新增一条"上游合并"记录：合并到的 upstream commit、
+  解决过的冲突文件、是否有本地修改被上游覆盖/废弃。
+- 若上游已用别的方式实现了某个本地功能（导致本地补丁不再需要），在 `status.md`
+  把对应条目标为"已放弃（上游已实现）"，并考虑回退本地补丁。
+
+## 规则 4：其他
+
+- `status.md` 属于仅本地文件，不向上游提 PR（除非团队明确决定）；
+  `AGENTS.md` 中仅本节（"本地 fork 维护规则"）是本地内容，向上游提 PR 时应剔除。