Zhucy123/source-code-mgmt

source-code-mgmt — DSH 源代码管理插件

English | 中文

版本：v1.25.0　|　更新日志见文末「版本历史」

界面语言跟随 DSH 设置实时切换：面板与 host 端消息自动使用 DSH 的语言（设置 → 通用 → 语言），中文 ↔ 英文即时生效，无需重启。

DSH Web GUI 源代码管理插件：一个「代码管理」面板把 ① 环境检查 → ② SSH 密钥与连接 → ③ 代码管理 → ④ 克隆仓库 → ⑤ 发布 npm 包 全流程串起来，GitHub / Gitee 双平台通用。环境检查自动检测 Git / GitHub CLI / SSH，缺工具可一键安装（按平台自适应、尽量免 sudo；gh 支持镜像下载源加速，Windows 亦可用），并带「检查更新」跟进新版本。

入口默认注册进 DSH 自带的右侧栏（不再保留单独的按钮）：在侧边栏「开始」页上，「代码管理」是与 工作区文件 / 新建终端 / 浏览器 / 壁纸引擎 并列的一张卡片，点开即在该栏里以页面形式打开面板。老宿主自动降级：装了 dsh-better-sidebar 时注册成它的侧边栏 Tab；两者都没有时（旧版宿主）才回退到右上角的 header 入口（有会话时放在「Session 日志」旁；无会话/新对话时钉在右上角，与有会话时逐像素同高）。不会占用左边栏。

功能

集成入口（按可用性自动选择，无需手动切换；任何时刻只有一个入口）：

• DSH 自带右侧栏（默认，harness ≥ 0.1.5）：「代码管理」作为侧边栏「开始」页（guide）上的一张卡片 + 该栏里的一个页面。点卡片即在右侧栏打开面板（官方行为：openTab(kind, { replaceTab: true })，替换掉「开始」页本身，像浏览器起始页那样）。卡片顺序排在内置三张（工作区文件 10 / 新建终端 20 / 浏览器 30）与其它插件（壁纸引擎 100）之后 = 110。

  • 没有独立按钮：座位 sidebar.right.pane.tab 存在即代表宿主自带右侧栏，此时插件完全不注册 header 入口 —— 这正是「去掉单独按钮」的落点。
  • 卡片标题/说明是函数（title: () => t("代码管理")），由宿主每次渲染时求值 ⇒ 切语言无需重新注册。
  • 面板用 variant: "tab"：填满该栏、不画自己的 ✕（关闭由宿主的 tab 栏负责）。

• 已安装 dsh-better-sidebar（旧宿主降级）：「代码管理」注册为它侧边栏的一个新 Tab 页面，点击侧边栏 Tab 直接打开面板；

• 两者都没有（旧宿主降级）：入口只注册在会话 header 里（两处严格互斥，任何时刻只有一个「代码管理」可见）——

  • ① 有活跃（非空白）会话时：经 conversation.session.header.utilities 槽位放在「Session 日志」旁（同款胶囊、间距 8px 一致）；
  • ② 空白（新对话）/无会话空态时：经常驻的 shell.overlay 槽注册一个常驻按钮，钉在右上角、且与「有会话时」那枚按钮完全同高。
    • 纵向与有会话时对齐：有会话时按钮在 header 的 utilities 行里，该行几何为 .header 的 padding-top: 10px + .titleRow 的 min-height: 30px（居中）⇒ 标题行占 y=10..40、中心 25px；按钮高 32px ⇒ top = 10 + (30 - 32)/2 = 9px。空态按钮取同一个 9px，所以两种形态切换时按钮不跳位。桌面壳里再叠加 --dsh-windows-titlebar-height（普通浏览器为 0），写法是 calc(var(--dsh-windows-titlebar-height, 0px) + 9px)。
    • 横向内缩 right: 48px，让开空态 header 右上角已有的「右侧栏展开按钮」：空态下 .headerBlank .headerCorner 带 margin-left: auto，把 ui-sidebar-right 的 ExpandButton（28×28 圆钮）顶到最右，其盒子位于视口右侧 12px～40px（.header 的 padding-right: 28px 减去 .headerCorner 的 margin-right: -16px 得到右缘 12px）。48 = 40 + 8（8px 与 header 内其它控件的间距一致），整个按钮落在圆钮左侧、互不相交。

  降级入口点击都打开同一个 dsh-better-sidebar 外观的右侧集成面板（内容放同一面板），并把主内容区往左推挤。

  座位「晚到」有宽限窗口（600ms）：sidebar.right.pane.tab 座位属于另一个包（ui-sidebar-right），加载器不保证顺序。若座位比本插件晚声明，这段时间里先不挂兜底按钮 —— 否则官方宿主上会先闪一个「代码管理」按钮、随后才被侧边栏卡片取代。窗口内座位出现 → 永远不挂；窗口耗尽仍没有 → 才按老宿主降级（老宿主本来就吃这条路径，晚 0.6s 出现按钮不可见）。全程零 I/O，只是一个计时器。

  关闭方式：右侧栏形态由宿主的 tab 栏负责（点 ✕ / 切页）；降级面板有三种 —— 面板右上角 ✕（标题行固定不滚动，内容滚到哪都在视口内）、按 Esc、或再次点「代码管理」按钮。

  降级面板顶部会让开窗口控件那条带（--dsh-frame-chrome-top）：桌面壳里 ─ □ ✕ 是 OS 绘制的覆盖层，任何贴到右上角的网页按钮都会被它压住、点不到（v1.24.1 修的正是这个「打开后关不掉」），所以面板整体从该带下方开始；原生全屏时该变量归零，面板仍用满整屏。

  刻意不注册进 DSH 自带左边栏（sidebar.footer.action）——那个入口会挤在左边栏「设置」上方，与侧栏自身的项混在一起。

  也刻意不去抢 DSH 自己的单占位槽：conversation.session.header.corner 已被自带右侧栏开关（ui-sidebar-right 的 ExpandButton）占用，conversation.session.header.leading 被自带侧栏开关（ui-sidebar 的 HeaderLeadingControls）占用；sidebar.panellist 的每一项 id 必须是真实主面板 id（会交给 layout.selectPanel），本插件没有主面板，注册进去只会得到点不动的死按钮。

检测只是激活时两次内存读取（座位声明 + ctx.get('sidebarRightTabs')），零 I/O、零网络，不影响 DSH 启动速度。

面板分五步（①②③ 为核心三步，④⑤ 为新扩展板块，默认折叠按需展开）：

① 环境检查

• 显示操作系统（美化名：Windows / macOS / Linux，对应底层 Node 平台标识 win32 / darwin / linux）
• 自动检测 Git、GitHub CLI 是否安装及版本（如 git version 2.55.0、gh version 2.97.0）
• 检测 SSH 客户端是否可用（解析到可用 ssh 即显示「已找到」）
• 缺工具时给安装指引 + 一键安装（按平台自适应、尽量免 sudo）：某工具未找到时，该行显示「❌ 未安装」+「复制安装命令」+「安装」按钮：
  • GitHub CLI（Linux / macOS）：免 sudo 用户级安装——从官方 GitHub Release 下载对应平台/架构的二进制包，解压后装到 ~/.local/bin/gh（目录不存在会自动创建，全程不需要管理员权限）；失败时自动回退系统包管理器。
  • Git（Linux）：apt / dnf / pacman（自动带 sudo -n；先探测 sudo 是否免密，需要密码时不再盲目执行，而是给出「请在终端手动执行」的指引 + 完整命令）。Git（macOS）：brew，无 brew 时走 Xcode 命令行工具（xcode-select --install，系统自带安装，含 git/ssh）。
  • SSH（Windows）：内置可选功能（需管理员）；SSH（Linux）：apt / dnf / pacman 的 openssh-client（同上 sudo 探测）；macOS 系统自带。
  • 复制安装命令与「安装」按钮走同一套平台自适应逻辑（不再固定显示 Windows 的 winget 命令）。
• 安装过程实时进度弹窗：点「安装」后弹出进度窗口，逐步显示「查询最新版本 → 下载 → 解压 → 安装 → 清理」及实时输出；完成后显示成功/失败原因。
• 需要重启时提示并一键重启：检测到安装后当前 host 进程无法立即识别（如 gh 装到了不在 PATH 的 ~/.local/bin）时，弹窗提示并显示「重启 DSH」按钮——点击后 host 通过 detached 辅助进程按原启动命令自动拉起新进程（机制同 dsh-update），页面短暂断开后刷新即可；若 host 已能识别（如设置了 DSH_SCM_GH 或 ~/.local/bin 在 PATH），则不打扰直接完成。
• 安装完成后自动重新检测。

② SSH 密钥与连接

• 平台选择：下拉选择代码托管平台 GitHub（默认） / Gitee，决定下面的 SSH 配置写入与连接测试目标
• 自动探测 ed25519 密钥：扫描 ~/.ssh/*.pub 中已存在的 ed25519 公钥——优先用 id_ed25519；否则用找到的第一个（支持任意命名的密钥，如 github_ed25519）；都没有则默认名 id_ed25519。状态行显示实际检测到的密钥文件名，SSH config 的 IdentityFile 也用它
• 一键生成 ed25519 密钥（无密码；本地已有 ed25519 密钥时复用，不会重复生成）
• 一键写入 SSH config，端口可选（见下）：
  • 443（穿墙，默认）：GitHub 写 github.com → ssh.github.com:443；Gitee 写 gitee.com:443。用于绕过封锁 22 端口的网络。
  • 22（标准）：GitHub 写 github.com → github.com:22（标准端点）。家宽 / 办公室 / VPS 通常直连即可。
  • 切换端口后再次点「配置 SSH(config)」会就地改写 ~/.ssh/config 里对应的 Host 块（不会留下重复块，也不动其它 Host）；状态行显示的是实际配置的端口（host 端解析 ~/.ssh/config 得出），不再是写死的 (443)。
  • 「测试连接」也按所选端口测试（ssh -T -p <port>），失败时提示「若是网络封锁 22 端口，请改用 443」。
• 测试连接 ssh -T -p <port> git@<host>（GitHub 走 ssh.github.com / github.com，Gitee 走 gitee.com）
• 显示公钥内容，方便复制上传到对应平台
• 检测 gh 是否已登录及账号

443 与「是否有代理」无关（常见误解）。 普通 HTTP 代理只对 git-over-HTTPS / curl 生效；OpenSSH 完全无视 HTTP_PROXY / HTTPS_PROXY（要走代理得配 ProxyCommand）。所以「我开了代理」并不等于「22 端口通了」——该不该用 443 取决于你的网络是否封锁 22 端口，因此这里交给用户自己选，而不是由插件猜测。

海外/正常网络需要 443 吗？——不需要。 「写 SSH config」本身是可选的（只有你点按钮才写 ~/.ssh/config）。GitHub 标准端点就是 git@github.com 走 22 端口，正常网络开箱即用：生成密钥 → 把公钥贴到 GitHub → 测试连接 → 推送，全程 22 端口。443（Host github.com → HostName ssh.github.com, Port 443）是 GitHub 官方支持的兜底方案，典型场景是国内网络、部分公司/校园网；只有当 443 也被封锁时才会反而不通（极少数网络）。Gitee 是国内平台，海外用户基本只会用到 GitHub。

③ 代码管理

• 跟随 ② 平台：本区所有「检测/新建/可见性」逻辑随 ② 的平台选择切换（GitHub 走 gh CLI，Gitee 走 Gitee OpenAPI）
• Gitee 令牌（仅 Gitee 模式显示）：输入 Gitee 私人访问令牌（需 projects 权限）→ 保存在本机 ~/.dsh/storages/source-code-mgmt-gitee.json（0600，不写入插件目录、不回传到浏览器/日志）；可一键清除；令牌无效会自动清掉
• 选择工作区：下拉选择 DSH 已登记的工作区文件夹，选中即加载
• 选择目录 →：下拉右侧按钮，可手动输入/粘贴目录绝对路径或点击「浏览…」弹出原生文件夹选择器；确认后持久化加入自定义目录列表（插件独立存储于 ~/.dsh/storages/source-code-mgmt-dirs.json，不写入插件目录，开源不泄漏个人路径），下次打开无需重新选择；手动添加的目录会以自定义目录徽标显示，末端带 ✕ 可一键删除该下拉记录（只删记录，不删实际文件夹）
• 显示仓库状态：平台来源、分支、远程地址、待提交改动数、领先/落后远程、>100MB 文件
• 查看详情：有改动时「改动」行旁出现「查看」按钮 → 点击弹出窗口列出改动/新增/删除/重命名的文件或文件夹名称；所有可文本预览的文件（含新增/untracked 新文件）都可点击文件行展开查看内容——并排视图（左旧右新，删除行红底、新增行绿底），纯新增文件没有旧版本，只显示「新版本」一列；二进制文件不显示「查看」（内容无法按文本预览）；本地与远程存在差异时「同步」行旁出现「查看」按钮 → 点击弹出窗口显示本地领先/落后的具体提交列表；无改动或已一致时不显示按钮
• 本地 Git 工作流（不改动远程同步逻辑）：
  • 「改动」弹窗里每个文件行有暂存 / 取消暂存按钮（按 git status 的 XY 状态区分 staged/unstaged），并显示「已暂存 / 未暂存」标记
  • ③ 面板仓库名上方有提交信息输入框 + 「提交」按钮（仅 git 仓库且有改动时显示）——可写自定义提交信息，不再用固定 message；留空则自动生成
  • 「分支」行旁有**「切换」**按钮 → 弹窗列出分支，点选即 checkout
  • 「分支」行旁有**「历史」按钮 → 弹窗列出提交（hash+subject+author+date），每条可查看**（并排 diff）、revert、cherry-pick（后两者带确认框，因为会改写历史）
• 远程按平台 + 当前账号匹配：③ 的「远程 / 同步」只认「属于当前平台的远程」且 owner 等于当前登录账号（GitHub 平台 = gh 账号如 Zhucy123 名下，Gitee 平台 = Gitee 令牌账号如 Zhucy2100 名下）。这样：
  • 切到 Gitee 时不读 GitHub 的 origin，只读 gitee.com 的远程；
  • github.com 上属于别人/其他组织的仓库（如 deepseek-ai/deepseek-harness）不会被当作「用户自己的远程」显示，ahead/behind 也不对它计算；
  • 本地没有属于当前账号的远程时，「远程」显示「（无）」、不计算同步，只走「同名仓库检测 + 新建仓库并推送」形态。
• 创建 Git：当所选目录不是 git 仓库但远程已存在同名仓库时显示该按钮，仅执行 git init（+设默认身份），不拉取不推送，由用户自行决定下一步是拉取还是推送
• 新建仓库并推送：默认以文件夹名为仓库名（只读不可改），可选私有/公开；同名仓库已存在时按钮禁用并在下方提示「同名仓库已经创建」。若目录还是全新的（尚无任何提交），会先自动 git add + 生成一个初始提交再创建，避免推送时报 "no commits found"
  • GitHub：gh repo create --private|--public --source=. --push
  • Gitee：用令牌调 Gitee OpenAPI POST /user/repos 建仓，再设置 SSH 远程 git@gitee.com:<owner>/<name>.git 并 git push（走 ② 已配的 SSH 密钥）
• >100MB 文件处理：自动识别超过 100MB 单文件限制的文件——文件在一级子目录内则忽略整个一级目录（该文件夹为一整体），根目录独立文件则忽略单个文件；已存在于 .gitignore 的不重复添加，并显示「未上传原因」

④ 克隆仓库（Clone）

• 跟随 ② 平台：把已登录账号（GitHub 走 gh，Gitee 走 OpenAPI）名下所有远程仓库列出来，并自动标记本地是否已有同名 git 仓库（默认按「默认工作区 + 已登记工作区 + 自定义目录」判定）
• 克隆到目录：可选目标父目录（默认 = DSH 默认工作区），不选即克隆到默认位置；克隆走 SSH URL（git@github.com:… / git@gitee.com:…），成功后自动加入自定义目录列表，③ 里可直接选中
• 列表里「本地已有」的仓库不可重复克隆，其余每个仓库一个「克隆」按钮

⑤ 发布 npm 包（npm publish）

• 五步向导（在目标目录执行）：① 确认源 npm config get registry → ② 查看认证配置 npm config list（自动脱敏 token/auth/password）→ ③ 验证身份 npm whoami → ④ 预览打包 npm pack --dry-run（先看会发布哪些文件，不真正打包发布）→ ⑤ 发布 npm publish
• 登录与发布固定走官方源 https://registry.npmjs.org：即使你的全局 npm 配置是镜像源（如 registry.npmmirror.com——镜像只同步、不接受发布），whoami / npm login / npm publish 也统一带 --registry=https://registry.npmjs.org；状态区在检测到镜像配置时会黄色提示「发布将使用官方源」。
• 「打开终端执行 npm login」安全弹终端：先探测系统真实存在的终端程序（konsole / gnome-terminal / xterm 系等），再 spawn（并挂 error 监听兜底）——修复了旧版 spawn 不存在二进制时异步 ENOENT 未捕获、直接把 dsh host 进程打崩的问题；KDE 下用 konsole --separate 开独立窗口，不与宿主所在终端实例纠缠。找不到终端时明确返回手动命令指引，不再假装成功。
• 发布前必须勾选「我已核对以上内容，确认发布到 npm registry」才可点「发布」，防止误操作

数据加载时机（打开时联网、显示刷新中）

DSH 打开时不联网同步仓库，只预取静态的环境/SSH/工作区列表。打开插件、切换工作区、刷新状态、以及推送/拉取/暂存/提交等操作后，都会联网获取对应工作区的最新仓库状态，并显示「⟳ 刷新中…」提示——避免打开/重开/切换时显示可能过期的旧数据（如旧的「无改动」）。关闭面板再打开也会重新同步，不会停留在旧状态。

安装

本插件以 Profile Bundle 形态分发：package.json 声明了 dsh.bundle（携带 cordis.patch.yml 配置层），所以 dsh plugin --profile web add 一条命令装完即自动激活——无需手动编辑任何配置文件。

方式一：从 npm 官方包安装（推荐）

最省事的方式——只需一条命令，且不用先进 profile 目录，推荐给普通使用者。

在任意目录执行：

# 用 DSH 自带的插件命令（自动定位/初始化 web profile）
dsh plugin --profile web add source-code-mgmt

该命令在 web profile 目录里执行 pnpm add，成功后对账插件层：检测到本插件声明 dsh.bundle，会自动把它追加进 dsh.profile.bundles（见 ~/.dsh/profiles/web/package.json）并注册进 Cordis loader 树，一步装完即用。

装完完全重启 dsh web（不是刷新页面，而是要停掉旧进程后重新启动），然后浏览器 F5 刷新，「代码管理」入口即出现（已装 dsh-better-sidebar 时为侧边栏 Tab，未装时为右上角 Session log 旁的「代码管理」按钮 + 右侧集成面板）。

方式二：从本地目录安装（开发/测试）

Windows (PowerShell):

# 用 DSH 插件命令安装本地源码（link: 协议，符号链接，改源码即生效）
dsh plugin --profile web add link:C:/path/to/source-code-mgmt
dsh web

Linux / macOS:

dsh plugin --profile web add link:/home/yourname/path/to/source-code-mgmt
dsh web

方式三：从 GitHub 安装（分发场景）

Windows / Linux / macOS 通用:

dsh plugin --profile web add git+https://github.com/Zhucy123/source-code-mgmt.git
dsh web

git 安装会把源码实际拷贝到 node_modules，改动源码需重新 dsh plugin --profile web add ... 拉取（不像 link: 是符号链接、改源码即生效）。

验证安装是否成功

安装并重启后，可以核对以下几点：

1. 依赖已写入：~/.dsh/profiles/web/package.json 的 dependencies 里应有 source-code-mgmt。
2. 已加入配置层：~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 列表里应有 source-code-mgmt（dsh plugin add 自动写入，无需手动编辑）。
3. 符号链接已建立（link: 方式）：~/.dsh/profiles/web/node_modules/source-code-mgmt 指向源码目录（Windows 显示为 Junction）。
4. 重启后入口可见：已装 dsh-better-sidebar 时侧边栏出现「代码管理」Tab；未装时右上角 Session log 旁出现「代码管理」按钮，点击展开右侧集成面板。

常见排障

使用步骤

1. 重启 dsh web 并刷新浏览器
2. 点击「代码管理」入口（已装 dsh-better-sidebar 时点侧边栏 Tab，未装时点右上角 Session log 旁的「代码管理」按钮展开右侧集成面板）
3. 面板打开（联网获取当前工作区最新状态，显示「⟳ 刷新中…」，拉取完成即显示内容）
4. ①确认 Git / GitHub CLI 已安装 → ②生成密钥并测试连接 → ③选择工作区后推送或新建仓库

后端 API 路由

安全

所有路由均为 loopback-only（sec-fetch-site + Origin 校验），仅本机浏览器可访问，LAN/手机来源一律 403——与控制面板同一策略。

跨平台

• Windows / Linux / macOS 通用
• 用 process.platform 检测平台
• ~/.ssh 通过 homedir() 定位（Windows: C:\Users\用户名\ .ssh，Linux/macOS: /home/用户名/.ssh 或 /Users/用户名/.ssh）
• Linux/macOS 下 SSH config 自动设 0600 权限
• git / gh / ssh / ssh-keygen 二进制自动探测：启动时依次按 ①环境变量覆盖 → ②PATH 查找（Windows 加 .exe）→（仅 Windows）③Git 自带目录（usr\bin / bin）回退，最后兜底用裸命令名。因此只要装了 Git，即使 ssh 不在 PATH 里也能正常工作，换设备无需额外配置。
• 如需手动指定二进制路径，可用环境变量覆盖：DSH_SCM_GIT / DSH_SCM_GH / DSH_SCM_SSH / DSH_SCM_SSH_KEYGEN
• SSH 传输修复：Git for Windows 自带的 MSYS ssh.exe（usr\bin\ssh.exe）在被 detached/agent 进程调用时可能报 couldn't create signal pipe, Win32 error 5，导致 git push/git pull 失败。插件执行 git 远程命令时会自动注入 GIT_SSH 指向解析到的可用 ssh（通常为系统 OpenSSH C:\Windows\System32\OpenSSH\ssh.exe），避免该问题。
• 中文文件名兼容：git 默认 core.quotepath 会把含非 ASCII 字节的路径输出成八进制转义的引号串（显示为乱码）。插件对所有 git 调用统一注入 -c core.quotepath=false（直接输出原始 UTF-8 路径），并对仍带引号转义的路径做 parseGitPath() 反转义兜底——改动列表 / diff 里的中文文件名显示正常
• 缺工具一键安装跨平台（v1.15.0 起按平台自适应、尽量免 sudo）：GitHub CLI 在 Linux/macOS 直接免 sudo 用户级安装（官方二进制 → ~/.local/bin/gh，失败回退系统包管理器）；git/ssh 在 Linux 走 apt-get / dnf / pacman（先探测 sudo 免密，需要密码时给出手动命令指引而非静默失败），macOS 走 brew / Xcode 命令行工具，Windows 走 winget / 内置功能（回退 choco/scoop）。安装过程有实时进度弹窗，需要重启时提供一键重启 dsh。SSH 密钥探测、本地 Git 工作流、并排 diff 等在三个平台行为一致；「浏览目录」的原生选择器仅 Windows 可用，macOS/Linux 上请在输入框直接填路径（可手动输入粘贴）。

开发

git clone https://github.com/Zhucy123/source-code-mgmt.git
cd source-code-mgmt
# 在本地 DSH 测试（安装到 web profile，自动激活）
dsh plugin --profile web add link:$(pwd)

• 改动 lib/client.js（浏览器端）→ 刷新页面即生效
• 改动 lib/index.js（host/Node 端）→ 刷新页面即可让面板重新检测（toolInstalled 按当前 PATH / ~/.local/bin 实测）；如 host 端 API 仍为旧版，重启 dsh web 进程一次

版本历史

v1.25.0（当前）

变更：入口默认注册进 DSH 自带的右侧栏，「代码管理」不再是一个单独的按钮：

• 需求：把插件默认注册进 DSH 的侧边栏，而不是保留右上角那个独立按钮。
• 背景（先说清「侧边栏」指哪个）：截图里被圈掉的是右上角那枚「代码管理」按钮；红圈标出的位置是右侧栏「开始」页上 工作区文件 / 新建终端 / 浏览器 / 壁纸引擎 那张卡片列表下面的空位。那四张卡片来自 DSH 自带右侧栏（ui-sidebar-right）的 guide（sidebar.right.pane.tab 座位 + sidebarRightTabs.register({ guide })），并不是 sidebar.footer.action（左边栏底部）——左边栏早在 v1.1.2 起就明确不碰。
• 实现：激活时 slots.inject('sidebar.right.pane.tab', …) —— 座位声明了就是这个宿主自带右侧栏，回调跑没跑即天然的能力门（不嗅探版本号，少一个漂移源）。回调里：
  • ctx.get('sidebarRightTabs').register({ id: 'source-code-mgmt/sidebar', kind: 'source-code-mgmt', title: () => t('代码管理'), guide: [{ id: 'panel', order: 110, title, description, icon: RepoIcon }] }) —— 这张 guide 条目就是「开始」页上的卡片；
  • slots.register({ name: 'sidebar.right.pane.tab', key: 'source-code-mgmt/sidebar' }, () => h(ScmPanel, { variant: 'tab' })) —— 卡片点开后在该栏里渲染的页面。key 必须等于 tab 类型的 id：宿主 TabSlot 用 definition.id 作 entryKey 派发 tab 本体，写错就会「卡片点开了但面板空白」。
  • 卡片顺序 order: 110：内置三张是 10 / 20 / 30，壁纸引擎（dsh-plugin-wallpaper-engine）是 100，所以本卡片排在其后、落在列表末尾。
  • title / description 是函数，宿主每次渲染都求值 ⇒ 切语言不需要重新注册（旧的 better-sidebar 路径因为收的是字符串，才需要 subscribe 后重注册）。
• 「去掉单独按钮」的落点：座位存在时根本不注册 header 两处入口 —— 不是「注册了再隐藏」。分支顺序 ①官方右侧栏 → ②dsh-better-sidebar → ③header 兜底，先成立者独占入口。
• 座位晚到的宽限窗口：sidebar.right.pane.tab 属于另一个包，可能比本插件晚声明。新增 SCM_FALLBACK_GRACE_MS = 600：这段窗口内先不挂兜底按钮（否则官方宿主上会先闪一个按钮再被卡片取代），窗口内座位出现 → 永远不挂，窗口耗尽才降级。全程零 I/O。
• 服务晚到：座位声明了 ≠ sidebarRightTabs 服务已就绪，故 ctx.get 短轮询（250ms × 40 ≈ 10s）后才放弃并回落 ③；tab 本体注册包在 ctx.effect 里，让 DSH 在插件卸载时自动注销（避免 fiber 已 dispose 时抛 INACTIVE_EFFECT）。
• 老宿主不受影响：装 dsh-better-sidebar 的走 ②（原逻辑不动）；两者都没有的走 ③（header 两处入口的原几何、互斥判定全部保留）。
• 测试：开发期用 4 个针对性回归文件覆盖本条改动 —— verify-entry-runtime.test.mjs（32 项，三段分支 + 卡片形状 + 图标尺寸 + 流体布局 + 卸载清理）、verify-sidebar-entry.test.mjs（16 项，「忠实宿主模型」：座位按宣告纪元重跑注入、keyed 座位拒绝重复 key、ctx.effect 按注入作用域回收、卸载按 LIFO / FIFO 两种顺序都验、注册抛异常路径，以及「兜底只能从路由里挂」的结构断言）、verify-sidebar-adversarial.test.mjs（16 项对抗式：能不能让官方宿主冒出独立按钮 / 能不能把用户搞成「零入口」）、verify-sidebar-postfix.test.mjs（3 项，独立复核者所写）。这些测试文件已在本版发布前删除（见下方「变更范围」），此处保留它们的结论作为改动依据的记录。
• 独立复核（本轮最有价值的部分）：由一位独立验证者对照真实 app.asar 逐条核对宿主契约（座位名/guide 排序/entryKey = definition.id/图标 size 22|26/openTab(kind,{replaceTab:true})/无 patterns 也能按 kind 打开/keepMounted 确实有语义），并用对抗用例查出 4 个真实缺陷，随后全部修掉：
  1. 两个入口并存：座位晚于本插件声明、且装了 dsh-better-sidebar 时，官方卡片会把 ② 的 Tab 也留着 —— 交接时只拆了 header 兜底，没拆 ②。修法：拆出 betterEntryActive（入口归属）与 hasBetterSidebar（是否安装，面板据此隐藏自带 Git 工作流）两个概念，官方成功路径同时 teardownBetterTab()。
  2. 插件彻底不可达：座位被宿主收回（自身重载）时，清理路径带着 stoppedByHost=true，恢复逻辑被跳过 ⇒ 一个入口都不剩。修法：座位回收不再设该标记，改为走统一的 routeToFallback() 恢复；stoppedByHost 只留给「插件卸载」与「② 已接管」。
  3. 重试阶梯其实只覆盖 5 秒：刻度被当成「距 apply 的绝对延时」而非「间隔」，[500,500,750,1000,1500,2000,3000,5000×7] 因此挤在头 5s 内烧完（注释却写「约 44s」）。后果：官方座位在、服务 10s 后才发布的宿主永远停在兜底按钮上。修法：改为累加调度（retryAt += interval，末级 ≈44s），并让重试在服务真正就绪时重新尝试官方注册。
  4. 服务超时后无法恢复：officialGaveUp 曾被当作永久放弃。修法：它只表示「这一轮 40×250ms 探测结束」，重试阶梯看到服务已就绪会把官方卡片换上、拆掉兜底。 另修一处口径错误：installHeaderFallback 原本用 hasBetterSidebar 当门，而该标记在官方入口赢下后仍为 true ⇒ 兜底永远挂不上（与缺陷 2 同类的不可达）。
• 第二轮复核又抓出 2 个问题（都已修）： 5. 注册抛异常时会多出一个入口：官方注册被拒（宿主 id 撞车时 tabs.register 会抛）的 catch 分支直接调 installHeaderFallback()，绕过了「② 已接管入口」的判断 —— 若此刻 ② 的 Tab 正挂着，屏幕上就是「Tab + header 按钮」两个入口。修法：该分支改走 routeToFallback(true)。（第一轮我曾以为 installHeaderFallback 里的 betterEntryActive 门是冗余防御，这个判断是错的：它在「抛异常」这条路径上是唯一的拦截点。） 6. 死状态：officialGaveUp 在改成「非永久」之后所有读取都被移除，只剩写入 ⇒ 是误导下一个读者的死变量（相关注释还在描述已不存在的门）。修法：整个删除，重入只由 officialCleanup/officialInstalled 两个条件表达。
• 有界窗口的精确边界：独立复核实测，服务最晚约 54s 出现的宿主仍能升到官方卡片（50s 可升、54s 不可）—— 因为 44.25s 的最后一级会再起一轮 40×250ms 探测。这是刻意保留的有界窗口，不是缺陷。
• 第二轮变异测试：独立复核跑了 10 个变异体，9 个被杀；唯一存活的正是上面的死状态（据此删除）。我这边补了「注册抛异常」路径的专项用例：单独改任一门都会被另一门掩盖，双变异（catch 直调兜底 + 拆掉 betterEntryActive 门）下用例确实失败 —— 说明该不变量被测到。
• 第三轮复核：独立复核确认死状态已清除、注释无残留、行为不变（18/18 × 两种卸载顺序；1000 条随机事件序列下「同时存在的入口数」恒为 1、注册表 0 违规），并逐条攻击了抛异常路径（不会零入口 / 不会重复注册 / 不会半个注册 / 无泄漏定时器）。另把「服务最晚多久出现仍能升级」实测到 53s 可、54s 不可（与代码注释、README 一致）。它还诚实披露了自己两个测试夹 bug（ctx.effect 归属与 carriers() 短路），并复跑了受影响结论。
• 补上最后一处覆盖缺口：前两轮里 installHeaderFallback 的 betterEntryActive 门与「catch 走路由」这两处，单独改任一处都无法从行为上观察到（路由先拦住）。除了保留双变异用例，另加一条结构断言：全文件里 installHeaderFallback( 只能有 1 处调用、且必须在 routeToFallback 内部 —— 这样将来有人在别处直调（正是第二轮那个重复入口 bug 的形态）会立刻失败。实测：单独把 catch 改回直调，这条断言即失败。
• 变异测试：上述每条不变量都做了变异验证（去掉宽限窗口 / 卡片 order 提前 / body key 与 id 不一致 / better-sidebar 抢在官方前 / 去掉 ② 交接拆除 / 座位回收恢复被阻断 / 阶梯改回绝对延时 / 停止重试升级 / 注册抛异常路径绕过路由 → 对应用例均失败）。
• 本轮之后清理：按用户要求，本插件的测试文件已全部删除（14 个 *.test.mjs + smoke-test.mjs + verify-en-dict.mjs）。保留 tools/ 下的 i18n 工具链（i18n-apply.mjs、i18n-extract.mjs、client-en.json、host-en.json）—— 它们是生成 lib/client.js 内联英文词典的脚本与数据源，删掉后词典就只能手改。上面的测试结论与变异测试结果作为本轮改动的历史依据保留。
• 变更范围：lib/client.js（桌面版无需操作，自动热重载；host 端未改）、tools/client-en.json、README.md、README.en.md、package.json，以及删除 tools/ 下 15 个测试文件。版本号 1.24.4 → 1.25.0（新功能用次版本号）。

v1.24.4（历史）

修复：面板打开后，窗口顶栏仍然有一条白缝（v1.24.3 的补带只补了面板那一段）：

• 现象：重启后白缝依旧 —— 顶栏在面板左缘仍是断开的。
• 根因：v1.24.3 补的那条带宽度写的是 panelW（跟面板同宽），但白缝的位置并不都在面板宽度内 —— 面板宽度随拖拽变化，补带宽度跟着变就总会留下没补到的段。
• 修复：补带改为 left: 0; right: 0 横贯整个窗口宽度。左半部分本来就是同色的原生顶栏，重复铺同色无副作用；右半部分把缺的那段补齐。不再依赖面板宽度 —— 拖拽改宽、开合面板都不会在顶栏留下任何缝。顺带删掉了为同步宽度而加的 chromeRef/getChromeEl（不再需要）。
• 回归测试：断言补带必须 left: 0; right: 0 横贯整宽（变异测试验证过：改回 panelW 宽会失败）。
• 变更范围：lib/client.js（桌面版无需操作，自动热重载）、tools/verify-close-button.test.mjs、README.md、README.en.md、package.json。版本号 1.24.3 → 1.24.4。

v1.24.3（历史）

v1.24.3（历史）

修复：面板打开后，窗口顶栏那一段出现明显色差（白条）：

• 现象：打开「代码管理」后，窗口最顶部那条原生标题栏在面板上方变成白色，左半（正常内容上方）仍是原来的浅灰 #f9fafb —— 中间在面板左缘形成一条硬缝。
• 根因（推挤的连带副作用）：桌面壳的 40px 顶栏是由 .BynINW_frame（及其 :before）用 --dsw-specific-sidebar-fill（= --dsw-static-neutral-bluish-50，#f9fafb）画出来的，而 frame 在 #root 里。本插件为了让位，用 .LAYOUT_CSS 把 #root 收窄了 panelW：#root { margin-right: var(--scm-push); width: calc(100% - var(--scm-push)) }。顶栏跟着 #root 一起被收窄，于是在面板左缘戛然而止；面板上方那一段没人画，露出页面底色（--dsw-alias-bg-layer-1 = #ffffff）。不是面板盖住了顶栏，而是顶栏被推挤截断了。
• 修复：在面板 portal 里补一条与顶栏同高、同宽（面板宽）的色带，用同一个 token var(--dsw-specific-sidebar-fill, transparent) 填充，顶栏于是横贯整个窗口宽度、看不出接缝。
  • pointerEvents: "none" —— 这条带只负责上色，鼠标事件照旧穿透给底下的原生拖拽区域，不改变顶栏原有的拖动行为；
  • 高度用 SCM_CHROME_TOP（普通浏览器下为 0px → 高度 0、整块不可见，与改造前一致）；原生全屏下同样归零，不会多出一条带；
  • 拖拽改宽时它必须跟面板同步改宽（否则顶栏会随拖拽裂开一条缝）：makeResizeHandler 相应多接一个 getChromeEl，逐帧同时写面板与色带的 width。
• 回归测试（tools/verify-close-button.test.mjs，9 项，本次新增 1 项）：断言 portal 里必须存在这条带、用的是 --dsw-specific-sidebar-fill、高度等于 SCM_CHROME_TOP、pointerEvents: "none"、带 ref 且 makeResizeHandler 拿到了它（并用变异测试验证：去掉色带的背景后该断言确实失败）。
• 变更范围：lib/client.js（刷新页面即生效）、tools/verify-close-button.test.mjs、README.md、README.en.md、package.json。版本号 1.24.2 → 1.24.3。

v1.24.2（历史）

修复：面板顶部那条灰带盖住了说明文字（v1.24.1 引入的回归）：

• 现象：打开「代码管理」后，标题「源代码管理」下方压着一条灰色横带，把「按顺序完成：①环境检查 → …」那行说明文字盖住/挤掉。
• 根因：v1.24.1 为让 ✕ 常驻，把标题行做成了 position: sticky 并给了它一层底色（--dsw-alias-bg-layer-1）。sticky 行是浮在内容之上的——它不会把后续内容推开，只是悬停在那里，于是底色正好压住从下面滚上来