diff --git a/frontends/slash_cmds.py b/frontends/slash_cmds.py
index dfd778ef..9566477f 100644
--- a/frontends/slash_cmds.py
+++ b/frontends/slash_cmds.py
@@ -152,16 +152,32 @@ def build_update_prompt(args_text: str = "") -> str:
         return (
             "Update this GenericAgent checkout from the official upstream "
             "https://github.com/Lsdefine/GenericAgent .\n"
-            "1. Fetch upstream; identify the current branch and whether there are any local "
-            "commits ahead of upstream.\n"
+            "1. Run `git fetch upstream`; identify the current branch and whether there are "
+            "local commits ahead of upstream.\n"
             "2. Show a concise preview: recent upstream commits not yet local "
             "(short hash + subject + date) plus a changed-files summary.\n"
-            "3. Apply the update (uncommitted working-tree changes must always be preserved):\n"
-            "   - If local commits exist: merge upstream into the current branch, auto-resolving "
-            "conflicts in favor of upstream, and keep the local commits. A merge commit is acceptable here.\n"
-            "   - Otherwise: run `git reset --mixed upstream/main` so local `main` aligns exactly "
-            "with upstream/main, automatically resolving conflicts in favor of upstream. Keep the local changes but do not create any new commits.\n"
-            "4. Finish with a short summary: branch HEAD, changed files, conflicts/resolutions.\n"
+            "3. Align the COMMIT HISTORY to upstream (upstream wins):\n"
+            "   - If local commits exist: `git merge upstream/main` into the current branch, "
+            "resolving any conflicts in favor of upstream; keep the local commits (a merge commit is fine).\n"
+            "   - Otherwise: `git reset --mixed upstream/main` so the history of local `main` "
+            "matches upstream/main exactly. Do NOT create any new commit.\n"
+            "4. IMPORTANT: also reconcile the WORKING TREE; step 3 alone is not enough. "
+            "`git reset --mixed` and `git merge` only move history and the index. They do not "
+            "rewrite files that already hold uncommitted local edits, so those stale files keep "
+            "shadowing upstream's latest. That is why 'HEAD is aligned but the files are still "
+            "old'. Reconcile per file:\n"
+            "   a. `git diff --name-only upstream/main` lists every tracked file whose working-tree "
+            "content differs from upstream.\n"
+            "   b. Decide upstream-first per file. A stale leftover, or a local edit that reverts "
+            "an upstream feature to an older form, takes upstream: back it up, then "
+            "`git checkout upstream/main -- <file>`. A genuine local enhancement upstream lacks "
+            "(local config, key-template placeholders, fork-only features) stays, re-applied on "
+            "top of upstream's latest instead of overwriting it.\n"
+            "   c. Upstream wins; keep local only where it adds value upstream lacks. Never "
+            "`git add -A`, never blanket whole-branch checkout, never blindly preserve everything.\n"
+            "5. Do not create any git commit. Back up any file before overwriting it.\n"
+            "6. Finish with a short summary: branch HEAD, distance vs upstream, per-file outcome "
+            "(took upstream / kept+adapted local), and where backups went.\n"
             "\n"
             "#### Say 'Congratulations! 🎉' to the user\n"
             "After a successful update, say: \"Congratulations! 🎉 You have successfully "
@@ -175,12 +191,21 @@ def build_update_prompt(args_text: str = "") -> str:
     return (
         "请你更新当前 GenericAgent 仓库，官方上游为 "
         "https://github.com/Lsdefine/GenericAgent 。\n"
-        "1. 先 fetch upstream；识别当前分支，以及是否存在领先 upstream 的本地 commit。\n"
+        "1. 先 `git fetch upstream`；识别当前分支，以及是否存在领先 upstream 的本地 commit。\n"
         "2. 给出简洁预览：本地尚未包含的 upstream 最近提交（短 hash + 标题 + 日期）及变更文件摘要。\n"
-        "3. 执行更新（工作区未提交的改动始终要保留）：\n"
-        "   - 若存在本地 commit：将 upstream 合并进当前分支，自动解决冲突且优先上游。\n"
-        "   - 否则：执行 `git reset --mixed upstream/main`，使本地 `main` 与 upstream/main 完全对齐，自动解决冲突且优先上游。本地修改保留但不要进行commit。\n"
-        "4. 最后给出简短小结：分支 HEAD、变更文件、冲突/解决方式。\n"
+        "3. 先对齐【提交历史】到上游（优先上游）：\n"
+        "   - 若存在本地 commit：`git merge upstream/main` 合并进当前分支，冲突一律优先上游，保留本地 commit（可产生 merge commit）。\n"
+        "   - 否则：执行 `git reset --mixed upstream/main`，使本地 `main` 的提交历史与 upstream/main 完全对齐。不要创建任何新 commit。\n"
+        "4. 重要：还须核对【工作区文件】，止步于第 3 步并不够。`git reset --mixed` 与 `git merge` "
+        "只移动提交历史与索引，不会重写那些已带未提交本地改动的文件，于是这些过时文件继续覆盖在上游"
+        "最新版之上。这正是“HEAD 已对齐，但文件其实还是旧的”的根因。逐文件核对：\n"
+        "   a. `git diff --name-only upstream/main` 列出工作区内容与上游不一致的全部 tracked 文件。\n"
+        "   b. 每个文件按优先上游判断。过时残留、或把上游特性改回旧版的本地改动，取上游：先备份，再 "
+        "`git checkout upstream/main -- <file>`。上游没有且仍有效的本地增强（本机配置、密钥模板占位、"
+        "fork 专属功能）保留，并在上游最新版上重新适配，而非整文件覆盖上游。\n"
+        "   c. 优先上游；本地仅保留上游缺失且有价值的部分。禁止 `git add -A`、禁止整分支 checkout 覆盖、禁止盲目全保留。\n"
+        "5. 不要进行任何 git commit。覆盖任何文件前先备份。\n"
+        "6. 最后给出简短小结：分支 HEAD、与上游差距、逐文件处理结果（取上游 / 保留并适配本地）、备份位置。\n"
         "\n"
         "#### 向用户说 'Congratulations! 🎉'\n"
         "更新成功后，请对用户说：\"Congratulations! 🎉 你已成功更新 GenericAgent！\"\n"