From 82e330c7d0f6c30da90b68df194d005a5660d6c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Timeless=E5=B0=8F=E5=B8=85?= <1018008088@qq.com>
Date: Wed, 21 Oct 2026 18:16:47 +0800
Subject: [PATCH] =?UTF-8?q?docs(git):=20=E8=AE=B0=E4=B8=8B=20push=20?=
 =?UTF-8?q?=E8=B5=B0=20SSH=20+=20=E6=8B=89=E5=AF=B9=E7=AB=AF=E4=B8=B2?=
 =?UTF-8?q?=E5=8F=A3=E5=88=97=E8=A1=A8=E8=A6=81=E5=AF=B9=E6=96=B9=E6=89=B9?=
 =?UTF-8?q?=E5=87=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

两个同范围的坑, 顺手记掉:

1. **push 走 SSH.** 远端 HTTPS 没配 credential helper, 非交互式 push 会卡在
   "could not read Username"。已经把 origin 的 push URL 指到 SSH (fetch 仍走 HTTPS),
   直接 `git push` 就能用; 也记了显式 URL 的退回写法, 以及 fetch 要用 SSH 才能刷新
   `origin/main` (否则 git status 里的"领先 N"是假的)。

2. **拉对端的串口列表需要对方用户批准** (新旧版本都是), 对方没批准就是 15 秒超时 ->
   列表空。这看着像 bug 其实不是, 别去加"自动跳过审批"。
---
 AGENTS.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 4ac8db2..4e2ad70 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -161,6 +161,8 @@ UDP discovery on **47800**, chat WS on **47900**, file HTTP on **47901**. All th
     (老版本本来就支持 `kind:'serial'`), 只有 USB 字节桥在混版本时用不了 —— 而那功能已下线。
     代价: 协议里那个 `'usb'` 帧名和实际内容对不上, 改的时候别手贱"顺手改对" —— 会把
     所有还在跑旧版本的对端一起踢下线。
+    另注: **拉对端的串口列表要对方用户批准** (新旧版本都这样), 对方没点批准就是 15 秒超时 ->
+    列表空 + 报"超时"。这是审批机制不是 bug, 别去加"自动跳过审批"的逻辑。
 
 11. **未读/角标: 正在看的会话必须立刻清未读, 且不能被 `savedPath` 拦下来.**
     踩过的坑: `App.vue` 的 `message:received` 里先判断 `if (!savedPath) return` (等文件落地再算未读),
@@ -178,6 +180,20 @@ UDP discovery on **47800**, chat WS on **47900**, file HTTP on **47901**. All th
 - `deviceName`, `downloadDir`, `notifications`, `autoStart` live in `~/AppData/Roaming/local-net-msg/config.json` via `electron-store`. Edit the file directly while dev is stopped.
 - `data/app.db` — SQLite DB. DELETE to reset all devices/messages. Auto-migrates on next launch.
 
+## 提交与推送
+
+远端是自建 Gitea (`https://git.xsinfo.vip/xiaoshuai/LocalNetMsg.git`)。**HTTPS 没有配 credential helper**，非交互式 `git push` 会卡在 `could not read Username` 上 —— 所以 push URL 已经指到 SSH：
+
+```
+origin  https://git.xsinfo.vip/xiaoshuai/LocalNetMsg.git (fetch)
+origin  git@git.xsinfo.vip:xiaoshuai/LocalNetMsg.git      (push)
+```
+
+fetch 走 HTTPS、push 走 SSH，直接 `git push` 就能用。SSH key 失效时退回：
+`git push git@git.xsinfo.vip:xiaoshuai/LocalNetMsg.git main:main`（显式指定 URL 不改 remote 配置）。
+
+拉远端最新提交用 `git fetch git@git.xsinfo.vip:xiaoshuai/LocalNetMsg.git main:refs/remotes/origin/main` —— 否则 `origin/main` 是陈的，`git status` 里的 "领先 N" 是假的。
+
 ## Packaging gotcha
 
 `release/` contains an `app.asar` Windows cannot delete while the previous app instance holds a file handle. Build now writes to `dist-Electron\` to dodge this. If you ever switch back, kill the running app first or you'll get EPERM.