dsh-github-flow 0.3.0 → 0.4.0

package/docs/architecture.md

@@ -25,55 +25,65 @@
 │     │   - AI_AGENT=dsh 注入 [gh 官方 agent 识别·可配置开关]            │        │
 │     │   - UpdateChecker (源可选探测 + 24h 缓存 + Fail-Safe)          │        │
 │     │   - UpgradeManager (跨平台自适应 + 互斥锁 + macOS PATH 补全)   │        │
-│     │   - spawnWithStdin (密文通道: spawn+stdin.end + kill 超时)   │        │
+│     │   - ProxyManager (环境变量集中路由 + 统一网络分发)             │        │
+│     │   - 模块化子系统 (src/executor/):                             │        │
+│     │     · git-parser.ts (无 I/O 纯文本解析纯函数)                 │        │
+│     │     · version-utils.ts (语义化版本比较纯函数)                 │        │
+│     │     · process-utils.ts (spawnWithStdin 密文流控与字节截断)    │        │
+│     │     · platform-guide.ts (跨平台安装引导与升级建议)            │        │
 │     └──────┬───────────────────────┬────────────────────────┬──────┘        │
 │            │                       │                        │               │
 │            ▼                       ▼                        ▼               │
 │  ┌──────────────────┐    ┌──────────────────┐    ┌───────────────────────┐  │
-│  │  9 大 Agent 工具  │    │  人类 Slash 指令 │    │   Host HTTP WebServer │  │
+│  │  14 大 Agent 工具 │    │  人类 Slash 指令 │    │   Host HTTP WebServer │  │
 │  │  (defineTool DSL)│    │  /gh status      │    │ (Effect Disposer 清理)│  │
-│  │  - pr (+ready·   │    │  /gh upgrade     │    │ - /api/github/overview│  │
-│  │    revert·update)│    │  /gh help        │    │ - /api/github/action  │  │
-│  │  - issue (+delete│    └──────────────────┘    │ - /api/github/refresh │  │
-│  │    ·transfer·pin·│                            │ - /check-update (并行)│  │
-│  │    lock·status)  │                            │ - /upgrade (一键自动) │  │
-│  │  - run (+workflow│                            │ - /update-settings    │  │
-│  │    系列·download)│  (workflow_enable/disable │  │ - /proxy (全局代理)   │  │
-│  │  - repo (+search │   启停·list/view·download) │ - /auth (轻量探针)    │  │
-│  │    三域+read_    │                            └──────────┬────────────┘  │
-│  │    file &read_dir)│                                       │               │
-│  │  - api (逃生门)  │   (search 三域=issues/prs/commits；     │               │
-│  │  - release       │    read_file/read_dir 免clone读取)      │               │
-│  │  - secret (stdin │                                        │               │
-│  │    +variable 域) │                                        │               │
-│  │  - skill         │                                        │               │
-│  │  - help (元指南) │                                        │               │
-│  └────────┬─────────┘                                       │               │
-│           │                                                 │               │
-│           ▼                                                 │               │
-│  ┌──────────────────────────────────┐                       │               │
-│  │  Markdown 渲染引擎 (renderers/)  │                       │               │
-│  │  - 列表表格化压缩 70%+ Token     │                       │               │
-│  │  - 状态徽章/超链接/转义防破损     │                       │               │
-│  │  - 高危确认卡片/敏感字段隔离      │                       │               │
-│  └──────────────────────────────────┘                       │               │
-└─────────────────────────────────────────────────────────────┼───────────────┘
+│  │  - pr (+attach)  │    │  /gh upgrade     │    │ - /api/github/overview│  │
+│  │  - issue (+attach│    │  /gh help        │    │ - /api/github/action  │  │
+│  │  - run (workflow)│    └──────────────────┘    │ - /api/github/refresh │  │
+│  │  - repo (read/sr)│                            │ - /api/github/branches│  │
+│  │  - api (逃生门)  │  (workflow_enable/disable │  │ - /branch-switch      │  │
+│  │  - release       │   启停·list/view·download) │ - /api/github/git-    │  │
+│  │  - secret & var  │                            │   watch (定向监听)    │  │
+│  │  - skill         │  (search 三域=issues/prs/ │ - /check-update (并行)│  │
+│  │  - label (CRUD/cl│   commits; read_file/dir)  │ - /upgrade (一键自动) │  │
+│  │  - ruleset(check)│                            │ - /update-settings    │  │
+│  │  - cache (治理)  │                            │ - /proxy (全局代理)   │  │
+│  │  - gist (分享)   │                            │ - /auth (轻量探针)    │  │
+│  │  - status (大盘) │                            └──────────┬────────────┘  │
+│  │  - help (元指南) │                                       │               │
+│  └────────┬─────────┘                                       ▼               │
+│           │                                      ┌───────────────────────┐  │
+│           │                                      │ git-watcher (独立服务)│  │
+│           ▼                                      │ - .git/HEAD & index   │  │
+│  ┌──────────────────────────────────┐            │ - 800ms 防抖/35s 超时 │  │
+│  │ Markdown 渲染引擎 (renderers/)   │            └───────────────────────┘  │
+│  │ - common.ts: 单元格清洗/通用徽章 │                                       │
+│  │ - 11领域模块: pr/issue/run/repo/ │                                       │
+│  │   release/skill/label/ruleset/   │                                       │
+│  │   cache/gist/status 独立渲染     │                                       │
+│  │ - 统一门面出口 markdown.ts 兼容  │                                       │
+│  └──────────────────────────────────┘                                       │
+└─────────────────────────────────────────────────────────────┬───────────────┘
                                                               │
 ┌─────────────────────────────────────────────────────────────┼───────────────┐
 │                        DSH Web Client                       ▼               │
 │                                                                             │
-│   ┌──────────────────────────────────┐    ┌─────────────────────────────┐   │
-│   │       全局驾驶舱 (Main Slot)      │    │  右侧栏面板 (Right Sidebar)  │   │
-│   │   - 账号全局所有 GitHub 仓库      │    │  - 五 Tab 互斥 (Git/未提交/ │   │
-│   │   - 本地工作区矩阵透视           │    │    PR/Issues/Actions)       │   │
-│   │   - 三维待办 Issues (药丸筛选)   │    │  - Git 记录与分支同步全景   │   │
-│   │   - 用户提单 / 分配待办 / 我发起 │    │  - 提交详情居中弹窗 (可滑动)│   │
-│   │   - 顶部升级通知横幅 (Banner)    │    │  - 下滑自动分页加载更多     │   │
-│   │   - 动态数据新鲜度胶囊与 SWR 缓存│    │  - 快捷操作网格与设置入口   │   │
-│   │   - 四分区设置弹窗 (同步/代理/   │    │  - 官方标准 Git 矢量图标    │   │
-│   │     更新源/关于)                │    │  - 「插件」身份徽章 (直达)  │   │
-│   │   - 「插件」身份徽章 (关于直达)  │    │                             │   │
-│   └──────────────────────────────────┘    └─────────────────────────────┘   │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 模块化 UI 架构 (src/ui/ ➔ 经 scripts/build.mjs 拓扑聚合单一 Bundle)  │   │
+│   │                                                                     │   │
+│   │  · styles.ts (1290行自适应 CSS, 构建期紧凑压缩)                      │   │
+│   │  · icons.ts (Octocat, Git 官方菱形分支矢量组件, 插件徽标)           │   │
+│   │  · storage.ts (LocalStorage SWR 状态机与偏好存储)                   │   │
+│   │  · components/ (分支下拉/认证引导/升级通知/离线横幅/状态胶囊)       │   │
+│   │  · modals/ (Commit 详情弹窗 / 4分区全局设置弹窗)                    │   │
+│   │  · panels/ (首页全景大面板 workspace-panel.ts)                      │   │
+│   │                                                                     │   │
+│   │ 核心组装入口 (src/client.ts, ~1,260 行高内聚):                      │   │
+│   │  - applyTabState (纯 DOM 互斥状态应用, 满足单测白盒契约)            │   │
+│   │  - renderGithubRepoView (五 Tab 核心视图: Git/未提交/PR/Issue/Run)   │   │
+│   │  - GithubRightbarBody (右侧栏主体, 状态引用解耦与时序安全守护)       │   │
+│   │  - apply(ctx) (Cordis Client 插件安装入口与槽位注入)                │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -93,100 +103,72 @@
 
 ### 2.3 上下文 Token 保护与防御性输出包装 (Token Budget Guard)
 - 所有的 `gh` 查询原生采用 `--json <fields>` 结构化投影；
-- 对长文本输出（如大型 PR 的完整 `diff`、CI 失败步骤日志）设置安全截断阈值（默认 24KB），采用码点安全切割与二分查找字节截断，保留头尾关键上下文并添加显式截断标记，杜绝撑爆模型上下文；
-- 列表与详情输出经独立 Markdown 渲染引擎（`src/renderers/markdown.ts`）转化为高密度表格与卡片（带状态徽章、可点击超链接与竖线转义防护），实测 20 条 PR 列表输出压缩 70%+ Token；
+- 对长文本输出（如大型 PR 的完整 `diff`、CI 失败步骤日志）设置安全截断阈值（默认 24KB），采用码点安全切割与二分查找字节截断（`src/executor/process-utils.ts`），保留头尾关键上下文并添加显式截断标记，杜绝撑爆模型上下文；
+- 列表与详情输出经独立 Markdown 渲染引擎（`src/renderers/` 7 大领域模块）转化为高密度表格与卡片（带状态徽章、可点击超链接与竖线转义防护），实测 20 条 PR 列表输出压缩 70%+ Token；
 - 所有 Agent 工具的输出统一经过归一化，列表自动打包为 `{ items, count }`，标量打包为 `{ result }`，100% 严丝合缝契合 DSH 工具网关模式约束；
-- **gh 版本守卫降级链（runGuarded）**：preview 命令与新特性按 `minVersion` 门槛路由——版本达标直通主命令、不足走 `fallback` 降级链路（结果携带 `degraded/degradedReason` 结构化标注，**降级不是静默的**，渲染层对 degraded 结果显式追加链路说明）、无降级时报错附平台升级指引；版本探测自身失败 fail-open 直通（守卫是路由优化不是安全边界）。版本比较采用数值分段（杜绝 `'2.96.0' > '2.100.0'` 字典序陷阱），探测结果 30s TTL 缓存且只缓存成功值；
+- **gh 版本守卫降级链（runGuarded）**：preview 命令与新特性按 `minVersion` 门槛路由——版本达标直通主命令、不足走 `fallback` 降级链路（结果携带 `degraded/degradedReason` 结构化标注，**降级不是静默的**，渲染层对 degraded 结果显式追加链路说明）、无降级时报错附平台升级指引；版本探测自身失败 fail-open 直通（守卫是路由优化不是安全边界）。版本比较采用数值分段（`src/executor/version-utils.ts`，杜绝 `'2.96.0' > '2.100.0'` 字典序陷阱），探测结果 30s TTL 缓存且只缓存成功值；
 - **AI_AGENT 识别信号注入**：每次 gh 子进程启动注入 `AI_AGENT=dsh`（gh detect.go 最高优先级通用信号）——gh ≥2.99 自动切换 text-only spinner、≥2.100 命令误用时打印完整 help（模型可据此自我纠正）、telemetry 归因到 dsh；旧版 gh 忽略该变量零副作用。经 `agentEnvInjection` 配置开关（默认开启）可恢复 gh 原生行为。
 
 ### 2.3.1 高危操作确认与敏感值安全通道 (Safety Confirmation & Secret stdin Channel)
-- 不可逆写操作（`merge` / `close` / `issue delete`（物理删除）/ `issue transfer`（跨仓库迁移）/ `pr revert`（远端创建反向 PR）/ `release delete` / clobber 覆盖上传 / `secret delete` / `skill install`）强制要求 `confirm: true` 显式参数，未确认时仅返回影响评估卡片，不产生任何远端或本地副作用；
-- 密钥明文仅经子进程标准输入传递（`spawnWithStdin` 通道：`spawn` + `stdin.end(data)` 半关闭写入——`execFile` 的 `input` 选项在实测环境从不真正写入管道，密文通道此前从未生效过），全程不出现在命令行参数、进程列表与工具输出中；渲染层对 secret 输出采用独立实现，从结构上隔离「绝不渲染 value 字段」这条安全红线。secret 与 variable（CI 明文，get 可回显）的渲染走**两个物理独立的函数**——安全语义靠函数边界而非同一函数的分支隔离，防未来重构互相污染。
+- 不可逆写操作（`merge` / `close` / `issue delete`（物理删除）/ `issue transfer`（跨仓库迁移）/ `pr revert`（远端创建反向 PR）/ `release delete` / clobber 覆盖上传 / `secret delete` / `skill install` / `label delete`（物理删除且解绑）/ `cache delete all`（全量清空缓存）/ `gist delete`（代码片段永久删除））强制要求 `confirm: true` 显式参数，未确认时仅返回影响评估卡片，不产生任何远端或本地副作用；
+- 密钥明文仅经子进程标准输入传递（`spawnWithStdin` 通道：`spawn` + `stdin.end(data)` 半关闭写入），全程不出现在命令行参数、进程列表与工具输出中；渲染层对 secret 输出采用独立实现，从结构上隔离「绝不渲染 value 字段」这条安全红线。
 
 ### 2.3.2 产物落盘纪律 (Artifact Download Discipline)
-- **目录固定派生，永不暴露路径参数**：构建产物下载（`run download` 等）的落盘目录由插件从 `~/.dsh/data/dsh-github-flow/artifacts/<owner>/<repo>/<run_id>/` 三级固定派生，不向调用方暴露任何目录参数——这是 GHSA-39wj-f2f4-978v（gh <2.102 符号链接路径穿越）的核心防线：用户无法注入 `../` 或符号链接目标，攻击面收敛到唯一一个 `mkdirSync(recursive)` 调用点，且目录天然按仓库与 run 隔离、可整体清理；
-- **低版本安全提示而非硬拒绝**：gh <2.102 时下载仍可执行（受控仓库场景是合理需求），但返回值携带 `securityNote` 升级指引；需要自定义落盘位置的场景显式引导经 `github_api` 手动拉取；
+- **目录固定派生，永不暴露路径参数**：构建产物下载（`run download` 等）的落盘目录由插件从 `~/.dsh/data/dsh-github-flow/artifacts/<owner>/<repo>/<run_id>/` 三级固定派生，不向调用方暴露任何目录参数——这是 GHSA-39wj-f2f4-978v（gh <2.102 符号链接路径穿越）的核心防线；
+- **低版本安全提示而非硬拒绝**：gh <2.102 时下载仍可执行，但返回值携带 `securityNote` 升级指引；需要自定义落盘位置的场景显式引导经 `github_api` 手动拉取；
 - **下载后零本地符号化操作**：插件对落盘产物仅做递归枚举（相对路径 + 大小清单），不执行链接、移动或执行类操作。
-未来任何新增下载类能力（如 gist 资产）必须引用本节纪律，而非各自重述。
-
-### 2.4 原生浅色/深色主题自适应与快捷操作网格
-- 全面对齐 DSH 官方 DSW 语义设计变量，基于 `body[data-ds-dark-theme]` 驱动无闪烁双模式切换；
-- 右侧栏快捷操作栏彻底废弃失效的阻塞弹窗，全面采用官方直达模式（查看所有 Issues、查看 PRs、Compare / New Issue），享有 100% 官方富文本体验。
-
-### 2.5 Cordis 微内核标准规范
-- **按需依赖声明**：显式声明核心必需服务 `['tools', 'commands']`，防止因无头运行环境缺少 `webServer` 或 `workspaceRegistry` 导致插件陷入 `PENDING` 假死状态；
-- **优雅动态探测**：通过 `if (ctx.webServer)` 探测环境，有 Web UI 服务时动态挂载路由，无 Web 环境时无缝降级为纯 CLI 工具；
-- **生命周期 Effect 闭环**：所有 HTTP 路由与命令注册均持有 Disposer 清理函数，插件热重载或重新挂载时自动彻底注销，零内存泄漏；
-- **配置自校验与服务暴露**：基于 Standard Schema 规范实现强类型校验与默认值注入，通过 `ctx.provide('github', executor)` 向生态插件暴露单例服务。
-
-### 2.6 三态环境诊断与交互引导状态机 (Setup & Authentication Lifecycle Guard)
-- **三态状态模型 (Three-State Machine)**：将环境就绪判定严格划分为 `NOT_INSTALLED`（未安装 CLI）、`NOT_LOGGED_IN`（已安装未登录）、`AUTHENTICATED`（已认证）三态，彻底消除“把未安装当作未登录”的状态屏蔽隐患；
-- **平台自适应安装策略**：后端探测到 `ENOENT` 时根据 `process.platform` 组装对应平台的安装命令（Windows: `winget`，macOS: `brew`，Linux: `apt/dnf`）与官方安装包地址；
-- **安全辅助与白名单终端唤起**：Web 端提供一键命令复制，后端 `/api/github/action` 提供安全白名单唤起接口，避免在前端模拟复杂交互式 PTY 的脆弱性；
-- **焦点感知自愈 (Focus Auto-Recovery)**：前端挂载 `window.focus` 事件监听，用户在外部浏览器或终端完成认证后切回 DSH 界面，自动静默重新探测并无缝更新 UI，实现零摩擦闭环体验。
-
-### 2.7 多维 Issue 身份判定与并发聚合引擎 (Multi-Dimensional Issue Engine)
-- **多重身份决策矩阵**：基于当前登录用户 `currentUser`（`auth.user`）对 Issue 执行身份归类：
-  - `reported`（用户提单）：`repoOwner === currentUser && author != currentUser`（外部访客在本人维护的仓库中提出的反馈）；
-  - `assigned`（分配待办）：`assignees.includes(currentUser)`（指派给本人的任务，跨仓库通用）；
-  - `created`（我发起的）：`author === currentUser`（本人亲自创建的 Issue）。
-- **三路并发搜索与 URL 去重**：后端在 `/api/github/global-overview` 中通过 `Promise.all` 同时发起 `--owner=@me`、`--assignee=@me`、`--author=@me` 检索，按 URL 唯一性合并去重并按最后更新时间统一降序排列；
-- **双端视图无缝打标**：驾驶舱提供四态响应式药丸筛选（全部/用户提单/指派待办/我发起的），右侧栏直接常驻展现当前工作区所属 Issue 任务清单与状态徽章。
-
-### 2.8 智能版本检测与跨平台一键升级引擎 (Update & Upgrade Engine)
-- **检查与 gh 链路完全并行**：
-  - 前端版本检查与 gh 环境探测（安装/登录/业务数据）**零依赖并行发起**（挂载即触发，仅 300ms 微延迟避让首屏），不串行等待概览返回，gh 环境异常时升级横幅照常展示；
-  - 服务端 `inFlightPromise` 请求合流 + 24 小时缓存，多面板同时挂载零请求风暴。
-- **更新源三态可选（UI 持久化 store 优先）**：
-  - 三态单选：官方源（默认）/ 国内镜像 npmmirror / 关闭自动检查；
-  - 持久化于 `~/.dsh/data/dsh-github-flow/update-settings.json`，保存即热切换并失效 24h 缓存（防"切换无效"感知）；
-  - **单源严格不互备**：显式选择的源不静默回落——镜像同步滞后正是选官方的理由，探测失败如实返回；
-  - 「关闭检查」语义为关自动提示不关能力：`/gh upgrade`（force）与一键升级路由不受熔断；
-  - 一键升级的 `NPM_CONFIG_REGISTRY` 跟随所选源（注入查询函数而非静态值，切源实时生效）。
-- **跨平台 Shell 调度与 macOS PATH 自愈**：
-  - **Windows**：采用 `cmd.exe /d /s /c`，彻底规避 PowerShell 5.1 不支持 `||` 导致的语法崩溃，启动仅 ~10ms；
-  - **macOS / Linux**：采用用户 Default Shell（`/bin/zsh` 或 `/bin/bash`）；
-  - **macOS PATH 智能补全**：针对 Mac 桌面端由 GUI (Finder/Dock) 启动不继承 `.zshrc` 的痛点，自动将当前 Node 目录、Apple Silicon `/opt/homebrew/bin` 及 Intel `/usr/local/bin` 动态注入 PATH 前端，确保 100% 发现 npm/pnpm。
-- **环境自省与源码保护防线 (Dev-Link Safe)**：
-  - 自动识别当前是否处于本地 Git 源码软链接模式（`link:`），若是则自动阻止 npm 覆盖，保护工作区源码；
-  - 自动识别桌面版 Profile 目录，无全局 CLI 时直接在 `~/.dsh/profiles/desktop` 下就地更新，无需用户具备终端知识。
-- **并发互斥锁与重启提示闭环**：
-  - 内存互斥锁防止连续点击导致包管理器 lockfile 竞争；
-  - 升级完成后明确提醒用户重启 DSH 服务以完全加载最新后端模块，同时支持立即刷新页面预览新界面。
-
-### 2.9 客户端持久化与 SWR (Stale-While-Revalidate) 极速直出架构
-- **0ms 首屏瞬间直出机制**：
-  - 在全景驾驶舱组件挂载时，`data` 初始值直接通过 `React.useMemo` 从 `localStorage` 读取上一次保存的历史快照；
-  - 消除传统加载时全屏阻塞卡顿，彻底抹平每次打开等待 8~15 秒的痛点，达到即开即用的丝滑体感。
-- **透明数据新鲜度与状态胶囊 (SyncStatusBadge)**：
-  - 胶囊状态精准映射：`[⏳ 后台同步中...]`、`[✅ 已是最新 (15:30)]`、`[📦 本地快照 (X分钟前)]`、`[⚠️ 同步超时已保留缓存]`；
-  - 支持人性化相对时间推导（刚刚、X分钟前、X小时前、X天前），消除用户对数据时效性的疑虑。
-- **设置中心 (GlobalSyncSettingsModal) 四分区**：
-  - **🔄 数据同步**：`⚡ 秒开模式 (SWR, 默认)` / `📋 仅手动刷新 (Manual Only)` 两态选择；
-  - **🌐 网络代理**：代理配置即时全局生效（写 proxy.json + 重应用 dispatcher，零插件重载）；
-  - **⬆️ 更新设置**：更新源三态选择（官方/镜像/关闭），保存即热切换并真实验证；
-  - **ℹ️ 关于**：插件身份信息（版本/仓库/npm/协议/求 Star）；
-  - 弹窗支持 `initialSection` 直开指定分区——插件徽标点击直开「关于」，齿轮默认「数据同步」。
-- **插件身份标识闭环**：
-  - 面板标题（驾驶舱/右侧栏）带「插件」徽标，明确标注界面由第三方插件 `dsh-github-flow` 提供（非 DSH / GitHub 官方）；
-  - 徽标点击派发全局事件打开「关于」弹窗（不直接跳浏览器）；多宿主同挂载时经可见性守卫防双层弹窗叠层；
-  - 右侧栏同样提供 ⚙️ 设置按钮，与主页复用同一弹窗组件，保存经事件总线双侧实时对齐。
-- **离线极端容灾保护 (Fail-Safe Offline Guard)**：
-  - 后台静默重验若遭遇断网、弱网或进程超时，界面平滑降级，**100% 保持旧数据完整可用**，绝不回退至空白占位或报错中断。
-- **数据链路超时防线**：
-  - 全部前端数据链路 fetch 绑定 `AbortController`（45s 兜底；登录探测 10s）——代理劫持回环地址等极端场景下用户得到明确超时出口，绝不永久转圈（未安装 gh 用户的刷新卡死修复）；
-  - 后端 `gh` 探测毫秒级返回 ENOENT/安装引导，前端安装引导卡（AuthGuideCard）承载唤起终端（stdio ignore，无 profile）等自愈出口。
-
-### 2.10 右侧栏五 Tab 互斥与本地 Git 状态全景架构 (Right Sidebar Tabs & Local Git Engine)
-- **五 Tab 响应式互斥布局**：
-  - 将右侧栏原本纵向堆叠的 PR / Issues / Actions / Git 状态与未提交清单彻底重构成水平紧凑 Tab（Git / 未提交 / PR / Issues / Actions），默认激活 Git 记录页，首屏高度收敛 60% 以上；
-  - 纯函数渲染约束与 DOM 级状态：`renderGithubRepoView` 坚守零 React Hooks 约束，激活态通过 `data-active-tab` 挂载在 DOM 容器上；根组件通过 `useEffect([data])` 与 `applyTabState` 联动，在 SWR 后台拉新完成触发重渲染时，自动重置回用户选择的 Tab，彻底解决后台数据刷新拽回默认 Tab 的缺陷。
-- **三段式提交日志与本地 0ms 秒开**：
-  - 本地领先（待 push）、远程领先（待 pull，快照口径）与最近提交历史；
-  - 采用 ASCII 单元/记录控制符（`%x1e` / `%x1f`）结构化解析 `git log`，一次性提取 fullSha、author、email、date、多行 body 说明与 `--stat` 文件改动统计，首屏 0ms 纯本地呈现，零网络失败风险；
-  - 默认展示 15 条，通过右侧栏容器 `onScroll` 触底（<80px）与点击双重触发向后分页拉取，伴随实时进度计数（如 `15 / 74`）。
-- **内嵌模态弹窗 (CommitDetailModal)**：
-  - 复用设置弹窗架构（`.dsh-github-modal-overlay` + `.dsh-github-modal-dialog`），挂载在右侧栏容器内部，天然受限于右侧栏边界居中，彻底消除传统 `<dialog>` 顶层穿透全屏居中的越界问题；
-  - 弹窗外框限制 `max-height: 84vh; overflow: hidden;`，正文区域 `flex: 1; min-height: 0; overflow-y: auto;`，完美支持上下滑动浏览数十行详细正文与修改文件统计，支持 Esc 键与点击遮罩随手退出。
-- **全库统一 Git 官方矢量图标**：全量替换各处的植物/字符符号为标准 Git 菱形分支官方矢量组件（`#1296db` SVG）。
 
+---
+
+## 3. 工程解耦与单文件瘦身规范 (Modularization Specs)
+
+为彻底解决单文件臃肿过长（如旧版 `client.ts` 超过 5,200 行、`executor.ts` 超过 1,100 行）的技术债，项目已全面落地分层解耦与自包含构建规范：
+
+### 3.1 后端执行引擎分层 (`src/executor/`)
+- [src/executor.ts](../src/executor.ts)（瘦身至 ~820 行）：保留 `GhExecutor` 类核心编排（命令白名单、执行通道、认证与版本缓存），完整 Re-export 子模块符号，保持 100% 向后兼容；
+- [src/executor/git-parser.ts](../src/executor/git-parser.ts)：纯文本解析器（`status -sb`、`log`、`branch -a`），无 I/O、无副作用；
+- [src/executor/version-utils.ts](../src/executor/version-utils.ts)：语义化版本数值分段比对纯算法；
+- [src/executor/process-utils.ts](../src/executor/process-utils.ts)：`spawnWithStdin` 进程管道流控与 UTF-8 字符边界截断算法；
+- [src/executor/platform-guide.ts](../src/executor/platform-guide.ts)：跨平台 CLI 安装引导与升级命令文本生成。
+
+### 3.2 渲染层领域化细分 (`src/renderers/`)
+- [src/renderers/markdown.ts](../src/renderers/markdown.ts)（瘦身至 14 行）：门面出口，统一聚合导出全部领域子模块；
+- [src/renderers/common.ts](../src/renderers/common.ts)：表格单元格字符净化、各类状态药丸 Emoji 徽章、API 降级透明注解；
+- `pr.ts` / `issue.ts` / `run.ts` / `repo.ts` / `release.ts` / `skill.ts`：6 大领域独立渲染格式化，避免跨工具改动合并冲突。
+
+### 3.3 本地 Git 元数据监听服务 (`src/git-watcher.ts`)
+- 独立底层服务模块，彻底剥离路由控制器内部的物理文件系统监听与定时器杂糅；
+- 靶向非递归监听 `.git/HEAD` 与 `.git/index`，内置 800ms 防抖合并、35s 超时熔断与物理句柄安全释放；
+- 使 [src/api/routes-actions.ts](../src/api/routes-actions.ts) 彻底移除对 `node:fs` 与 `node:path` 的直接依赖，路由函数回归纯粹的 HTTP 请求接收与响应。
+
+### 3.4 前端客户端解耦与自包含 Bundle 机制 (`src/ui/` + `src/client.ts`)
+- **源码物理剥离**：
+  - [src/client.ts](../src/client.ts)（由 5,290 行直降至 **1,263 行，瘦身 76%**）：仅保留右侧栏核心协同 `renderGithubRepoView` 与 `GithubRightbarBody` 及插件入口；
+  - 12 个独立子模块下沉至 [src/ui/](../src/ui/) 目录（样式 1,295 行、全景大面板 732 行、设置弹窗 561 行、业务卡片 60~290 行）；
+- **命名空间防护**：
+  - 严禁在与 `package.json` 的 `exports["./client"]` 同级创建名为 `client/` 的目录，统一命名为 `src/ui/` 与编译产物 `lib/ui/`，彻底杜绝模块解析器产生“同名文件 vs 目录”的歧义报错；
+- **自包含 Bundle 聚合器 (`scripts/build.mjs`)**：
+  - 构建脚本按严格拓扑顺序将 `lib/ui/` 子模块内联注入 `lib/client.js` 的 `window.__ModuleLoader__.load` 闭包中，移除 `export` 关键字；
+  - 保证 `GithubRightbarBody` 位于 `GithubWorkspacePanel` 之前（满足切片测试断言）；
+  - 对嵌入的 1,290 行纯 CSS 实施紧凑压缩，消除空行与多余注释，使编译产物从 5,282 行减至 4,008 行；
+- **React Hook 时序安全防线**：
+  - 组件内引用的 `useRef`（如 `containerRef`）必须在组件声明最前列初始化，严禁跨行下置引发变量提升 `undefined`；所有的 Ref 访问点必须配备 `containerRef && containerRef.current` 守卫，杜绝运行时渲染崩溃。
+
+---
+
+## 4. 自动化测试体系 (Test Suite)
+
+项目配备了 13 个独立阶段的全量自动化回归测试套件（`test/run-all.mjs`），覆盖 **562 项全量自动化测试断言**：
+- `phase1`：Issue / Run / PR / Repo / Help 命令装配与确认门禁；
+- `phase2`：Native Markdown 渲染与 Token 压缩率实测（>60% 降幅）；
+- `phase3`：Release 资产交付、Secret 密文管道与 Skills 检索；
+- `phase4`：工具装配完整性、版本一致性拦截与模糊边界防护；
+- `phase5`：网络代理配置有效性校验、环境注入与容灾降级；
+- `phase6`：插件版本更新检测、多源选择与跨平台自升级调度；
+- `phase7`：终端唤起真实反馈、更新源设置 UI 锚点与 45s 数据链路超时保护；
+- `phase8`：图片链接提取与图片下载；
+- `phase9`：README 提取与相对路径解析；
+- `phase10`：版本守卫降级链（runGuarded）、AI_AGENT 注入与命令白名单；
+- `phase11`：右侧栏五 Tab 响应式互斥、Git 提交记录与滑动分页；
+- `phase12`：工作区物理所有权隔离、SWR 离线快照防抹杀与安全分支切换；
+- `phase13`：云端定时自动同步生命周期、三选一互斥设置模型与右侧栏独占本地 git-watch 监听。

package/lib/api/routes-actions.js

@@ -3,6 +3,8 @@
  * 共同特征：POST 触发、读少写多、无缓存语义，与概览类路由的演进方向不同。
  */
 import { spawn } from 'node:child_process';
+import { hasGitDir } from '../workspace.js';
+import { watchGitMetadata } from '../git-watcher.js';
 import { isSafeExternalUrl, sendJson } from './route-helpers.js';
 /**
  * 构造「在新终端窗口运行命令」的平台命令（execFile 数组形态，不经 shell）。
@@ -226,6 +228,21 @@ export function registerActionRoutes(deps, executor, cacheMap, globalCache) {
                             sendJson(res, 200, { ok: true, message: '已唤起系统终端' });
                             break;
                         }
+                        case 'switch_branch': {
+                            const branch = typeof payload.branch === 'string' ? payload.branch.trim() : '';
+                            if (!branch) {
+                                sendJson(res, 400, { ok: false, error: '缺少目标分支名称' });
+                                return;
+                            }
+                            const r = await executor.switchGitBranch(cwd, branch);
+                            if (!r.ok) {
+                                sendJson(res, 400, { ok: false, error: r.error });
+                                return;
+                            }
+                            cacheMap.clear();
+                            sendJson(res, 200, { ok: true, currentBranch: r.currentBranch, message: `已成功切换到分支 ${r.currentBranch}` });
+                            break;
+                        }
                         default:
                             sendJson(res, 400, { ok: false, message: `未知的操作类型: ${payload.action}` });
                     }
@@ -236,4 +253,104 @@ export function registerActionRoutes(deps, executor, cacheMap, globalCache) {
             });
         },
     });
+    // 3. 读取当前工作区的所有 Git 分支列表（纯本地只读，毫秒级响应）
+    bindRoute({
+        kind: 'exact',
+        path: '/api/github/branches',
+        handler: async (req, res) => {
+            if (req.method !== 'GET') {
+                sendJson(res, 405, { ok: false, message: '仅支持 GET 请求' });
+                return;
+            }
+            try {
+                const url = new URL(req.url || '', 'http://127.0.0.1');
+                const cwd = url.searchParams.get('cwd') || undefined;
+                const result = await executor.getGitBranches(cwd);
+                if (!result) {
+                    sendJson(res, 404, { ok: false, error: '当前工作区不是 Git 仓库或无法读取分支' });
+                    return;
+                }
+                sendJson(res, 200, { ok: true, data: result });
+            }
+            catch (err) {
+                sendJson(res, 500, { ok: false, error: err?.message || '读取分支列表失败' });
+            }
+        },
+    });
+    // 4. 切换当前工作区的 Git 分支（带未提交变更防护与合法性校验）
+    bindRoute({
+        kind: 'exact',
+        path: '/api/github/branch-switch',
+        handler: async (req, res) => {
+            if (req.method !== 'POST') {
+                sendJson(res, 405, { ok: false, message: '仅支持 POST 请求' });
+                return;
+            }
+            let body = '';
+            req.on('data', (chunk) => { body += chunk; });
+            req.on('end', async () => {
+                try {
+                    const payload = body ? JSON.parse(body) : {};
+                    const cwd = payload.cwd || undefined;
+                    const branch = typeof payload.branch === 'string' ? payload.branch.trim() : '';
+                    if (!branch) {
+                        sendJson(res, 400, { ok: false, error: '缺少目标分支名称' });
+                        return;
+                    }
+                    const r = await executor.switchGitBranch(cwd, branch);
+                    if (!r.ok) {
+                        sendJson(res, 400, { ok: false, error: r.error });
+                        return;
+                    }
+                    // 核心联动：切换分支成功后，当前工作区缓存立即失效，确保后续拉取新分支数据
+                    cacheMap.clear();
+                    sendJson(res, 200, {
+                        ok: true,
+                        currentBranch: r.currentBranch,
+                        message: `已成功切换到分支 ${r.currentBranch}`,
+                    });
+                }
+                catch (err) {
+                    sendJson(res, 500, { ok: false, error: err?.message || '切换分支失败' });
+                }
+            });
+        },
+    });
+    // 5. 本地 Git 元数据定向监听（专供右侧栏开启「本地 Git 改动实时感知」时长轮询）
+    // 严格安全纪律：只针对 .git/index 与 .git/HEAD 实施定向非递归监听，严禁监听源码目录防句柄耗尽；
+    // 800ms 防抖合并；连接断开时自动关闭 watcher 释放系统资源（委托给底层 git-watcher 服务）。
+    bindRoute({
+        kind: 'exact',
+        path: '/api/github/git-watch',
+        handler: async (req, res) => {
+            if (req.method !== 'GET') {
+                sendJson(res, 405, { ok: false, message: '仅支持 GET 请求' });
+                return;
+            }
+            const url = new URL(req.url || '', 'http://127.0.0.1');
+            const cwd = url.searchParams.get('cwd');
+            if (!cwd || !hasGitDir(cwd)) {
+                sendJson(res, 400, { ok: false, error: '非 Git 仓库，无需监听' });
+                return;
+            }
+            let responded = false;
+            try {
+                const stop = watchGitMetadata(cwd, (event) => {
+                    if (responded)
+                        return;
+                    responded = true;
+                    sendJson(res, 200, { ok: true, ...event });
+                });
+                req.on('close', () => {
+                    if (!responded) {
+                        responded = true;
+                        stop();
+                    }
+                });
+            }
+            catch (err) {
+                sendJson(res, 500, { ok: false, error: err?.message || '建立监听失败' });
+            }
+        },
+    });
 }

package/lib/api/routes-overview.js

@@ -17,6 +17,7 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                 const url = new URL(req.url || '', 'http://127.0.0.1');
                 let cwd = url.searchParams.get('cwd');
                 const sessionId = url.searchParams.get('sessionId');
+                const force = url.searchParams.get('force') === 'true';
                 // 会话 ID → 物理路径，以及「最近活跃工作区」兜底，统一由 workspace 模块提供
                 if (!cwd && sessionId) {
                     cwd = findWorkspacePathBySession(sessionId) || null;
@@ -29,7 +30,7 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                 }
                 const now = Date.now();
                 const cachedData = cacheMap.get(cwd, now);
-                if (cachedData) {
+                if (cachedData && !force) {
                     sendJson(res, 200, {
                         ok: true,
                         data: { ...cachedData, updateInfo: checker.getQuickStatus() },
@@ -39,7 +40,25 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                     return;
                 }
                 const auth = await executor.checkAuth(cwd);
-                const repo = await executor.getRepoMetadata(cwd);
+                // 先行检查当前工作区是否真实包含 .git，无 .git 铁证判定为未关联仓库
+                const isGitRepo = hasGitDir(cwd);
+                const repo = isGitRepo ? await executor.getRepoMetadata(cwd) : null;
+                // 若当前工作区未关联 Git 仓库，直接返回纯净空状态，坚决不拉取远端数据
+                if (!isGitRepo || !repo) {
+                    const emptyData = {
+                        auth,
+                        repo: undefined,
+                        pullRequests: [],
+                        issues: [],
+                        issueStats: { total: 0, reported: 0, assigned: 0, created: 0 },
+                        runs: [],
+                        lastUpdated: new Date().toISOString(),
+                        updateInfo: checker.getQuickStatus(),
+                    };
+                    cacheMap.set(cwd, emptyData, now);
+                    sendJson(res, 200, { ok: true, data: emptyData, fromCache: false, cwd });
+                    return;
+                }
                 let pullRequests = [];
                 let issues = [];
                 let runs = [];
@@ -53,6 +72,52 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                         executor.run(['issue', 'list', '--json', 'number,title,state,author,labels,assignees,url,updatedAt', '-L', '10'], { cwd, timeoutMs: 8_000 }),
                         executor.run(['run', 'list', '--json', 'databaseId,name,status,conclusion,event,headBranch,url,createdAt', '-L', '5'], { cwd, timeoutMs: 8_000 }),
                     ]);
+                    // 核心数据拉取故障检测：若拉取核心业务数据遭遇失败（网络超时/断网/接口报错），
+                    // 绝对不能把失败伪装成「0 个 PR、0 个 Issue」并假装成功返回！
+                    const failures = [];
+                    if (!prsRes.ok)
+                        failures.push(`PR 获取失败: ${prsRes.error || '网络或接口异常'}`);
+                    if (!issuesRes.ok)
+                        failures.push(`Issue 获取失败: ${issuesRes.error || '网络或接口异常'}`);
+                    if (!runsRes.ok)
+                        failures.push(`Actions 获取失败: ${runsRes.error || '网络或接口异常'}`);
+                    if (failures.length > 0) {
+                        const failureReason = failures.join('；');
+                        // 若此前内存有缓存，保全已有缓存内容，附加 networkError 与 partialFailure
+                        const fallbackCached = cacheMap.getFallback(cwd) || cacheMap.get(cwd, now);
+                        if (fallbackCached && (fallbackCached.pullRequests.length > 0 || fallbackCached.issues.length > 0 || fallbackCached.runs.length > 0)) {
+                            sendJson(res, 200, {
+                                ok: true,
+                                fromCache: true,
+                                partialFailure: true,
+                                error: failureReason,
+                                data: {
+                                    ...fallbackCached,
+                                    networkError: true,
+                                    networkErrorReason: failureReason,
+                                    auth: { ...fallbackCached.auth, networkError: true, networkErrorReason: failureReason },
+                                },
+                                cwd,
+                            });
+                            return;
+                        }
+                        else {
+                            const freshData = {
+                                auth: { ...auth, networkError: true, networkErrorReason: failureReason },
+                                repo: repo || undefined,
+                                pullRequests: [],
+                                issues: [],
+                                issueStats: { total: 0, reported: 0, assigned: 0, created: 0 },
+                                runs: [],
+                                networkError: true,
+                                networkErrorReason: failureReason,
+                                lastUpdated: new Date().toISOString(),
+                                updateInfo: checker.getQuickStatus(),
+                            };
+                            sendJson(res, 200, { ok: true, partialFailure: true, error: failureReason, data: freshData, cwd });
+                            return;
+                        }
+                    }
                     if (prsRes.ok && Array.isArray(prsRes.data))
                         pullRequests = prsRes.data;
                     if (issuesRes.ok && Array.isArray(issuesRes.data)) {
@@ -96,6 +161,8 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                     freshExtras.commitLog = await executor
                         .getGitCommitLog(cwd, gitStatus ? gitStatus.hasUpstream : false)
                         .catch(() => null);
+                    // 5. 分支列表（纯本地毫秒级）：供右侧栏分支选择器 0ms 秒开，消除独立请求延迟与 404 风险
+                    freshExtras.branches = await executor.getGitBranches(cwd).catch(() => null);
                 }
                 const issueStats = calculateIssueStats(issues);
                 const freshData = {
@@ -166,6 +233,31 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                     const ownerIssuesRes = queryResults[2].status === 'fulfilled' ? queryResults[2].value : { ok: false };
                     const assignedIssuesRes = queryResults[3].status === 'fulfilled' ? queryResults[3].value : { ok: false };
                     const authorIssuesRes = queryResults[4].status === 'fulfilled' ? queryResults[4].value : { ok: false };
+                    // 检测全局拉取是否发生网络故障，绝不把网络失败当作「0 仓库、0 PR」伪造成功
+                    const globalFailures = [];
+                    if (!reposRes.ok)
+                        globalFailures.push(`仓库列表拉取失败: ${reposRes.error || '网络或接口异常'}`);
+                    if (!prsRes.ok)
+                        globalFailures.push(`个人 PR 拉取失败: ${prsRes.error || '网络或接口异常'}`);
+                    if (globalFailures.length > 0) {
+                        const globalNetReason = globalFailures.join('；');
+                        const fallbackGlobal = globalCache.getFallback('global') || globalCache.get('global', now);
+                        if (fallbackGlobal) {
+                            sendJson(res, 200, {
+                                ok: true,
+                                fromCache: true,
+                                partialFailure: true,
+                                error: globalNetReason,
+                                data: {
+                                    ...fallbackGlobal,
+                                    networkError: true,
+                                    networkErrorReason: globalNetReason,
+                                    auth: { ...fallbackGlobal.auth, networkError: true, networkErrorReason: globalNetReason },
+                                },
+                            });
+                            return;
+                        }
+                    }
                     if (reposRes.ok && Array.isArray(reposRes.data)) {
                         userRepos = reposRes.data.map((r) => ({
                             name: r.name || '',

package/lib/cache.d.ts

@@ -8,6 +8,8 @@ export declare class TtlCache<T> {
     private ttlMs;
     private maxEntries;
     private store;
+    /** 容灾备份底座：记录最后一次成功的有效快照，不受 TTL 过期或主动 refresh 清空的影响 */
+    private fallbackStore;
     /**
      * @param ttlMs 命中有效期；由面向用户的 cacheTtlMs 配置驱动
      * @param maxEntries 容量上限。键通常是工作区路径，一次会话就可能引入若干键，
@@ -16,6 +18,8 @@ export declare class TtlCache<T> {
     constructor(ttlMs: number, maxEntries?: number);
     get(key: string, now: number): T | undefined;
     set(key: string, data: T, now: number): void;
+    /** 获取最后一次有效成功的容灾底座数据（专供网络故障、超时时的 Fail-Safe 保全） */
+    getFallback(key: string): T | undefined;
     get size(): number;
     clear(): void;
 }

package/lib/cache.js

@@ -8,6 +8,8 @@ export class TtlCache {
     ttlMs;
     maxEntries;
     store = new Map();
+    /** 容灾备份底座：记录最后一次成功的有效快照，不受 TTL 过期或主动 refresh 清空的影响 */
+    fallbackStore = new Map();
     /**
      * @param ttlMs 命中有效期；由面向用户的 cacheTtlMs 配置驱动
      * @param maxEntries 容量上限。键通常是工作区路径，一次会话就可能引入若干键，
@@ -32,17 +34,29 @@ export class TtlCache {
     }
     set(key, data, now) {
         this.store.set(key, { data, time: now });
+        this.fallbackStore.set(key, data);
         while (this.store.size > this.maxEntries) {
             const oldest = this.store.keys().next();
             if (oldest.done)
                 break;
             this.store.delete(oldest.value);
         }
+        while (this.fallbackStore.size > this.maxEntries) {
+            const oldest = this.fallbackStore.keys().next();
+            if (oldest.done)
+                break;
+            this.fallbackStore.delete(oldest.value);
+        }
+    }
+    /** 获取最后一次有效成功的容灾底座数据（专供网络故障、超时时的 Fail-Safe 保全） */
+    getFallback(key) {
+        return this.fallbackStore.get(key);
     }
     get size() {
         return this.store.size;
     }
     clear() {
+        // 清空活动缓存以迫使后续请求重新发起网络拉取，但保留 fallbackStore 用于网络故障容灾
         this.store.clear();
     }
 }