sync: BOWEI_US 2026-09-25

bmem/SKILL.md

@@ -200,6 +200,54 @@ bmem add --machine --section "账号/服务配置" "gitea 账号 bowei，凭证
 2. 在服务端先核对精确目标，再对异常全局 Git 配置或注入脚本做可恢复隔离、重启并重新检查；不进行强推、仓库手术或不可恢复清理，除非另有明确授权。修复后的判断依据是**从客户端真正完成 fetch/clone**，不是 Gitea 网页、`ls-remote` 或容器自称 healthy。
 3. 立刻重跑 `bmem sync`。传输恢复后若出现真实 rebase 冲突，保留本地和远端语义，解决 `~/.bmem/repo` 及会重新覆盖仓库的本机 Markdown 工作副本，特别核对自动编号唯一；只做非强制推送，再次运行 `bmem sync`。
 4. 只有 `bmem sync` 返回成功、Git 拉取/推送成功、远端 `main` 与本地提交相同、客户端浅克隆可读，才报告 Markdown 层已同步；PostgreSQL 另按自身结果报告。若新故障持续，继续做安全范围内的诊断；真正缺少登录权限或需要额外授权时报告具体阻塞和所需输入，不把未同步状态遗留为“已完成”。
+
+### 项目记忆由谁同步：一个文件只能有一个归属
+
+项目记忆 `bmem_<prjID>.md` 躺在项目目录里，而项目目录往往已经被 Syncthing / SyncTrayzor
+整目录同步。**同一个可变文件有两个同步归属，就是冲突制造机**：git 这边 `write_back` 把仓库
+版本盖回工作副本，文件同步工具再忠实地把这次覆盖传播出去，可能抹掉别的机器几秒前的修改；
+两边同时改则留下 `.sync-conflict` 副本，记忆悄悄分叉而没人知道。
+
+所以 bmem 的规矩是：**项目目录已被文件同步工具管理时，项目记忆归它，git 不重复同步**
+（靠向上查找 `.stfolder` 自动识别，无需配置）。具体表现：
+
+- `bmem sync`：跳过该文件，并在报告里说明原因；`bmem.md` 与机器记忆不受影响（它们在用户
+  根目录，通常不在同步范围内）。
+- `bmem init`：**只有文件不存在时才创建骨架**，之后完全让给文件同步工具；也不会把仓库里
+  可能更旧的副本还原进来——那会被当成一次新编辑反向传播，覆盖别的机器上更好的版本。
+- `bmem delete`：**不删这个文件**。删掉会连带在所有机器上消失，而 delete 只应注销本机。
+  真要连别的机器一起删，用 `--delete-shared-doc`。
+- 任何命令发现 `bmem_*.sync-conflict-*.md` 都会明确报出来——那是记忆已经分叉的信号，
+  必须人工合并，机器不该替你猜哪份对。
+
+想改这个行为：`~/.bmem/config.toml` 的 `[git] project_doc_sync`，取
+`auto`（默认）/ `git`（总是走 git）/ `none`（bmem 永不同步它）。
+
+### 同步失败时它会自己去看服务端
+
+gitea 和中心 PostgreSQL 跑在同一台机器上（见全局记忆 G-0005 的两条登录方式）。
+同步失败时，`bmem sync` 会 SSH 上去诊断，并把**该跑却没跑的服务**拉起来，然后重试一次：
+
+```bash
+bmem sync                # 配置了维护主机就会自动检修（config.toml 的 auto_repair）
+bmem sync --repair       # 显式要求检修
+bmem sync --no-repair    # 这次别动服务端
+```
+
+它遵守两条规矩，理解它们比记住命令更重要：
+
+1. **先诊断再动手**。每一步修复都基于观察到的状态，不基于"大概是什么坏了"的猜测。
+2. **只恢复服务，不改配置**。可以做的：启动没在跑的 PostgreSQL、启动已停止的 gitea 容器、
+   重启一个在跑但 HTTP 不健康的容器。**不会做的**：改镜像版本、改 `listen_addresses`、
+   改 `pg_hba`、改任何认证设置——这些一律只报告，交给人决定。
+   区别在于：**把服务恢复到本该有的状态是可逆的，重新定义这个服务不是。**
+
+两种失败它只报告不处理：服务本身响应正常但 git 传输仍失败（pack 传输故障，按上一节交给
+tools-sync 阶段 1.5 的 gitea 医生；根因见 G-0006，G-0004 的“换镜像版本”已作废）；以及维护主机根本连不上。
+
+只有真正失败的那一半会被检修——PG 挂了不会顺手重启 gitea。路由会先走 tailscale，
+不通再自动回退到公网 frps。
+
 ## 多机与本机状态
 
 ```bash
@@ -280,7 +328,7 @@ bmem delete --yes --sync # 确认执行并同步给其它机器
 | 写记忆 | `bmem add --global\|--prj\|--machine [--section 节名] <内容>` |
 | 导入 Notes | `bmem notes [--check] [--session-summary F] [--facts F] [--sync]` |
 | 看多机/本机状态 | `bmem machines [--project P] [--json]` / `bmem sqlite [--schema] [--json]` |
-| 同步 | `bmem sync` |
+| 同步 | `bmem sync [--repair \| --no-repair]` |
 | 安装与初始化 | `bmem install` / `bmem init` |
 | 注销项目 | `bmem delete`（预览）/ `bmem delete --yes --sync`（执行） |
 | 帮助 | `bmem help` |