dsh-github-flow 0.2.0 → 0.2.1

package/README.en.md

@@ -57,8 +57,8 @@ Run in your DSH environment:
 # Scenario A: DSH Desktop Edition (Desktop Profile)
 dsh plugin --profile desktop add dsh-github-flow
 
-# Scenario B: DSH Web / CLI Environment
-pnpm dsh plugin add dsh-github-flow
+# Scenario B: DSH Web / CLI Environment (--profile is required by the official CLI; fill in your actual profile name)
+dsh plugin --profile web add dsh-github-flow
 ```
 
 > 💡 **Notice (24-Hour Supply-Chain Security Lock Window)**:  
@@ -85,12 +85,13 @@ Consolidates scattered GitHub endpoints into **9 core domain tools**, featuring
   * `list`: List open PRs with author, review decisions, and CI status (`state` / `author` / `limit` filters);
   * `view`: Inspect PR description, metadata, and mergeability;
   * `diff`: Retrieve complete code diffs (`stat_only` for file-change overview, safely truncated against token limits);
-  * `checks`: Audit CI status check rollups and test suites;
+  * `checks`: Audit CI gate status (pass/fail/skip category badges, owning workflow, and detail links);
   * `create`: Auto-create PRs (supports draft mode & `--dry-run`);
   * `checkout`: 🆕 Check out PR code to a local branch for sandboxed testing;
   * `status`: 🆕 Inspect merge conflict status (`CLEAN` / `CONFLICT`) for the current branch's PR;
   * `review`: Submit code reviews (`APPROVE`, `REQUEST_CHANGES`, `COMMENT`);
-  * `merge`: Merge pull requests (`squash` / `merge` / `rebase`, optional `delete_branch`; requires `confirm: true`).
+  * `merge`: Merge pull requests (`squash` / `merge` / `rebase`, optional `delete_branch`; requires `confirm: true`);
+  * `view_images`: 🆕 Download PR discussion screenshots (body + comments; `image_urls` targeting with budget-overflow resume list).
 
 ---
 
@@ -124,7 +125,8 @@ Consolidates scattered GitHub endpoints into **9 core domain tools**, featuring
   * `edit`: 🆕 Update title, body, and add/remove labels;
   * `develop`: 🆕 Create a linked development branch from an issue and check it out locally;
   * `comment`: Append debugging updates or notes;
-  * `close` (requires `confirm: true`) / `reopen`: Manage issue lifecycle states.
+  * `close` (requires `confirm: true`) / `reopen`: Manage issue lifecycle states;
+  * `view_images`: 🆕 Download issue attachment screenshots (body + comments; `image_urls` targeting with resume list).
 
 ---
 
@@ -136,6 +138,7 @@ Consolidates scattered GitHub endpoints into **9 core domain tools**, featuring
 
 * **Supported Actions**:
   * `view`: View repository metadata (default branch, stars, description, topics & license);
+  * `readme`: 🆕 Read repository README raw content (branch-selectable; relative-path screenshots auto-resolved and downloaded);
   * `sync`: 🆕 One-click fork sync with upstream to fix stale-fork CI gate failures;
   * `search_code`: Search code symbols in current or specified repositories;
   * `search_repos`: Search open-source GitHub repositories globally.
@@ -235,14 +238,15 @@ Located in the right drawer of every chat workspace:
 * **PR Status Pills**: Live PR inspection with CI checks and review badges;
 * **Workspace Open Issues List**: Direct issue task review with author badges and external links;
 * **Latest Actions Pipeline**: Real-time CI workflow status tracking;
-* **Quick Action Grid**: Open repo in browser, jump to Issues/PRs, create PRs with one click.
+* **Quick Action Grid**: Open repo in browser, jump to Issues/PRs, create PRs with one click;
+* **⚙️ Full Settings Access**: The sidebar offers its own settings button reusing the same settings modal as the cockpit (all four sections: Sync / Proxy / Update Source / About) — no need to switch back to the main page.
 
 <p align="center">
   <img src="./docs/images/2.png" alt="Session Right Sidebar Panel" width="100%" />
 </p>
 
 ### 3. Settings Center (Settings Modal)
-Click **`[⚙️ Settings]`** in the top right of the Cockpit to open the sectioned settings modal (left-side navigation, independently scrolling content; collapses to horizontal tabs on narrow screens):
+Click **`[⚙️ Settings]`** in the top right of the Cockpit (or the ⚙️ button in the right sidebar) to open the sectioned settings modal (left-side navigation, independently scrolling content; collapses to horizontal tabs on narrow screens):
 
 **🔄 Data Sync Section** — tune data fetching rhythm:
 * **Two Sync Strategies**:
@@ -258,6 +262,19 @@ Click **`[⚙️ Settings]`** in the top right of the Cockpit to open the sectio
 * **Visibility**: A `🌐 Proxy` badge appears in the cockpit title bar while active; hover to inspect the current proxy URL;
 * **NO_PROXY Exclusions**: `localhost` and `127.0.0.1` are forcibly included — loopback Web API requests are never hijacked by the proxy.
 
+**⬆️ Update Source Section** — choose which npm registry checks for new versions:
+* **Three options**: 🌍 npm official registry (default — new releases visible immediately) / 🇨🇳 npmmirror (fast in China; minutes-level sync delay) / ⛔ No update checks (only silences the upgrade banner; `/gh upgrade` and one-click upgrade remain available);
+* **Strict single-source**: the selected source is never silently swapped — probe failures are reported honestly;
+* **Detection & upgrade traffic follows the global proxy setting** (socks5 boundary stated honestly in the UI);
+* **One-click upgrade installs from the selected source** — consistent with version detection;
+* **Verify on save**: switching sources immediately probes the new registry and shows the latest version.
+
+**ℹ️ About Section** — plugin identity & project info:
+* Current running version, project description, GitHub repository, npm package page, and MIT license;
+* Star card — if the plugin helps your workflow, a Star on the repo powers continued iteration.
+
+> 🏷️ **Plugin Identity Badge**: Panel titles (cockpit & right sidebar) carry a small "Plugin" badge, clearly marking the UI as provided by the third-party plugin `dsh-github-flow` (not a DSH / GitHub official feature). Click the badge to open the About page.
+
 | 🔄 Data Sync Section | 🌐 Network Proxy Section |
 | :---: | :---: |
 | ![Settings Center · Data Sync](./docs/images/3.png) | ![Settings Center · Network Proxy](./docs/images/4.png) |
@@ -268,14 +285,16 @@ Click **`[⚙️ Settings]`** in the top right of the Cockpit to open the sectio
 
 Never miss an update! Built-in industrial-grade update management:
 
-1. **Business-First, Idle Background Detection**:
-   - Primary PR/Issue data loads and renders **instantly in milliseconds**;
-   - Update checks run **1.5 seconds later during idle periods**, ensuring zero impact on user workflows.
-2. **Dual-Registry Acceleration**:
-   - Prioritizes npmmirror for ultra-fast checks (50~150ms in mainland regions) with seamless fallback to official npmjs.
+1. **Parallel Detection, Zero gh-Dependency**:
+   - Update checks fire **in parallel with the gh environment chain** (install/login/business data) on mount — never serialized behind gh overviews; gh failures never block upgrade banners;
+   - Server-side `inFlightPromise` merging + 24h cache keeps multi-panel mounting storm-free.
+2. **Selectable Update Source** (see the "⬆️ Update Source" settings section):
+   - Defaults to the **npm official registry** (new releases visible immediately), or switch to **npmmirror** (minutes-level sync delay);
+   - Auto checks can be disabled entirely (only silences prompts — `/gh upgrade` and one-click upgrade stay available).
 3. **Cross-Platform One-Click Upgrade**:
    - **Click to Upgrade**: Click **`[⚡ Upgrade]`** in the UI to update in the background;
    - **Auto OS Adaptation**: Differentiates macOS and Windows; auto-injects Homebrew PATH variables on macOS GUI launches;
+   - **Registry Follows Setting**: One-click upgrades install from the source selected in Update Source settings;
    - **Source Protection**: Automatically aborts npm overwrites when running in local Git linked development mode (`link:`);
    - **Restart Guidance**: Clearly notifies users to restart DSH service to reload backend tools, with instant web refresh options.
 

package/README.md

@@ -57,8 +57,8 @@ gh auth login
 # 场景 A：DSH 桌面版 (Desktop Profile)
 dsh plugin --profile desktop add dsh-github-flow
 
-# 场景 B：DSH Web / CLI 工程环境
-pnpm dsh plugin add dsh-github-flow
+# 场景 B：DSH Web / CLI 环境（--profile 为官方 CLI 必填参数，profile 名按实际环境填写）
+dsh plugin --profile web add dsh-github-flow
 ```
 
 > 💡 **提示（新版本发布后 24 小时内的安全锁定期说明）**：  
@@ -85,12 +85,13 @@ pnpm dsh plugin add dsh-github-flow
   * `list`：列出当前仓库开放的 PR（带作者、审查判定、CI 门禁状态，支持 `state` / `author` / `limit` 过滤）；
   * `view`：查看指定 PR 详情、描述与元数据；
   * `diff`：获取 PR 的完整代码差异（`stat_only` 仅看文件变更概览，防大 PR 溢出）；
-  * `checks`：审查指定 PR 的 CI 门禁状态与检查套件结果；
+  * `checks`：审查指定 PR 的 CI 门禁状态（通过/失败/跳过分类徽章、所属工作流与详情链接）；
   * `create`：一键自动创建 PR（支持 draft 草稿模式与 `--dry-run` 预演）；
   * `checkout`：🆕 把 PR 代码检出到本地分支，Agent 可直接在沙箱跑测试验证改动；
   * `status`：🆕 查看当前分支关联 PR 的合并冲突状态（`CLEAN` / `CONFLICT`）；
   * `review`：提交代码审查意见（`APPROVE`, `REQUEST_CHANGES`, `COMMENT`）；
-  * `merge`：自动执行合并（支持 `squash` / `merge` / `rebase`，可指定 `delete_branch`；需 `confirm: true` 二次确认）。
+  * `merge`：自动执行合并（支持 `squash` / `merge` / `rebase`，可指定 `delete_branch`；需 `confirm: true` 二次确认）；
+  * `view_images`：🆕 下载 PR 讨论截图（正文+评论，支持 `image_urls` 精准提取与触顶续传清单）。
 
 ---
 
@@ -124,7 +125,8 @@ pnpm dsh plugin add dsh-github-flow
   * `edit`：🆕 修改标题、正文与增删标签；
   * `develop`：🆕 从 Issue 一键切出关联开发分支并本地检出，打通「读需求 → 写代码」闭环；
   * `comment`：在指定 Issue 中追加排查进展或评论；
-  * `close`（需 `confirm: true`）/ `reopen`：开启或关闭 Issue。
+  * `close`（需 `confirm: true`）/ `reopen`：开启或关闭 Issue；
+  * `view_images`：🆕 下载 Issue 报障截图（正文+评论全量提取，支持 `image_urls` 按 URL 精准提取，触顶自动返回续传清单）。
 
 ---
 
@@ -136,6 +138,7 @@ pnpm dsh plugin add dsh-github-flow
 
 * **支持操作 (`action`)**：
   * `view`：查看当前或目标仓库的元数据（默认分支、星标、描述、Topics 与开源协议）；
+  * `readme`：🆕 读取仓库 README 原文（支持指定分支，相对路径截图自动解析下载）；
   * `sync`：🆕 一键拉平 Fork 仓库与上游主干，解决贡献开源项目时 Fork 落后导致 CI 门禁失败；
   * `search_code`：跨仓库或当前仓库检索特定代码符号；
   * `search_repos`：跨全站检索 GitHub 开源仓库。
@@ -234,14 +237,15 @@ pnpm dsh plugin add dsh-github-flow
 * **PR 门禁状态药丸**：展示当前开放 PR，悬停查看 Checks 结果与审核意见；
 * **当前仓库 Open Issues 列表**：直接在侧边栏审查待办任务并提供直达链接；
 * **最新 Actions 构建流水线**：实时关注 CI 状态；
-* **快捷操作网格**：一键在浏览器打开仓库、直达 Issues/PRs、一键创建 PR。
+* **快捷操作网格**：一键在浏览器打开仓库、直达 Issues/PRs、一键创建 PR；
+* **⚙️ 完整设置入口**：右侧栏同样提供设置按钮，与主页复用同一设置弹窗（数据同步 / 网络代理 / 更新设置 / 关于 四分区完整可用），无需切回主页调整。
 
 <p align="center">
   <img src="./docs/images/2.png" alt="右侧栏工作区面板" width="100%" />
 </p>
 
 ### 3. 设置中心 (Settings Modal)
-点击全景驾驶舱右上角 **`[⚙️ 设置]`** 打开分区式设置弹窗，左侧分区导航、右侧内容独立滚动（窄屏自动折叠为横向页签）：
+点击全景驾驶舱右上角 **`[⚙️ 设置]`**（或右侧栏的 ⚙️ 按钮）打开分区式设置弹窗，左侧分区导航、右侧内容独立滚动（窄屏自动折叠为横向页签）：
 
 **🔄 数据同步分区**——调优数据拉取节奏：
 * **两种同步策略**：
@@ -257,6 +261,19 @@ pnpm dsh plugin add dsh-github-flow
 * **生效可视化**：代理启用时驾驶舱标题栏显示 `🌐 代理` 徽章，悬停查看当前代理地址；
 * **NO_PROXY 排除列表**：`localhost` 与 `127.0.0.1` 强制包含，本机 Web API 回环请求永不被代理劫持。
 
+**⬆️ 更新设置分区**——选择新版本检测所用的 npm 源：
+* **三态单选**：🌍 npm 官方源（默认，版本全球首发最及时）/ 🇨🇳 国内镜像 npmmirror（国内访问快，同步存在分钟级延迟）/ ⛔ 不检查更新（仅关闭自动提示横幅，`/gh upgrade` 与一键升级仍可用）；
+* **单源严格不互备**：显式选择的源不会被静默替换——选官方就只查官方，探测失败如实提示而非假装正常；
+* **检测与升级流量遵循全局代理设置**（与网络代理分区联动，socks5 边界在界面如实标注）；
+* **一键升级的安装源跟随选择**：选了镜像源，一键升级也走镜像安装；
+* **保存即验证**：切换源后立即用新源真实探测一次并回显最新版本号。
+
+**ℹ️ 关于分区**——插件身份与项目信息：
+* 当前运行版本、项目简介、GitHub 仓库地址、npm 包页面与 MIT 开源协议；
+* 求 Star 卡片——如果插件对你的研发有帮助，欢迎到仓库点个 Star 支持持续迭代。
+
+> 🏷️ **插件身份标识**：全景驾驶舱与右侧栏的标题旁均带有「插件」小徽标，明确标识界面由第三方插件 `dsh-github-flow` 提供（非 DSH / GitHub 官方功能）。点击徽标即可打开「关于」页面查看项目信息。
+
 | 🔄 数据同步分区 | 🌐 网络代理分区 |
 | :---: | :---: |
 | ![设置中心·数据同步分区](./docs/images/3.png) | ![设置中心·网络代理分区](./docs/images/4.png) |
@@ -267,14 +284,16 @@ pnpm dsh plugin add dsh-github-flow
 
 再也不用担心错过新功能！`dsh-github-flow` 内置了工业级的版本管理机制：
 
-1. **业务优先，闲时静默后置**：
-   - 打开 Web 界面时，**核心 PR / Issue 数据 100% 毫秒级优先拉取渲染**；
-   - 在所有业务数据渲染就绪后，前端延迟 1.5 秒利用空闲时间发起后台探针，**对主业务 0 阻塞、0 抢占**。
-2. **国内双源智能加速**：
-   - 默认第一顺位走 **阿里云/淘宝 npm 镜像**（国内延迟仅 50~150ms），超时自动无缝回退官方 npmjs 兜底。
+1. **业务优先，检查与 gh 链路完全并行**：
+   - 版本检查与 gh 环境探测（安装/登录/业务数据）**零依赖并行发起**（挂载即触发，仅 300ms 微延迟避让首屏渲染），不串行等待 gh 概览返回，gh 环境异常也绝不影响升级提示；
+   - 服务端 `inFlightPromise` 合流 + 24 小时缓存，多面板同时挂载零请求风暴。
+2. **更新源自主可选**（详见设置中心「⬆️ 更新设置」分区）：
+   - 默认走 **npm 官方源**（版本全球首发最及时），或切换 **国内镜像 npmmirror**（同步存在分钟级延迟）；
+   - 可完全关闭自动检查（仅关提示不关能力，`/gh upgrade` 与一键升级仍可用）。
 3. **跨平台一键自动升级**：
    - **界面直升**：在全景驾驶舱或右侧栏点击 **`[⚡ 一键自动升级]`**，插件在后台安全执行拉取；
    - **智能适配**：自动识别 macOS、Windows 与桌面版 Profile，Mac 环境下自动补全 Homebrew 环境变量；
+   - **安装源跟随设置**：一键升级的 registry 跟随「更新设置」所选源，与版本检测保持一致；
    - **源码保护防线**：检测到本地 Git 源码软链接模式（`link:`）时自动阻止覆盖，防止破坏开发工作区；
    - **成功自愈提示**：升级成功后明确提醒重启 DSH 服务以激活后端新工具，也可点击按钮立即刷新页面预览新界面。
 
@@ -327,9 +346,9 @@ pnpm dsh plugin add dsh-github-flow
         maxOutputBytes: 96000     # 单次命令 UTF-8 字节数硬上限，默认 maxOutputChars × 4
         defaultListLimit: 20      # 列表类查询默认返回条数（pr/issue/run/release/skill 通用）
         cacheTtlMs: 15000         # 单仓库概览缓存时长（毫秒，默认 15 秒）
-        checkUpdate: true         # 是否开启新版本自动检查提示（默认开启）
+        checkUpdate: true         # 是否开启新版本自动检查提示（默认开启；false 时熔断自动探测，显式升级不受限）
         updateCheckIntervalMs: 86400000 # 检查更新间隔（毫秒，默认 24 小时）
-        registryUrl: ''           # 自定义私有 npm 镜像地址（留空则自动选用 npmmirror 与 npmjs）
+        registryUrl: ''           # 自定义私有 npm 镜像地址（留空走「更新设置」所选源，界面设置优先）
         proxyUrl: ''              # 代理地址预置默认值（如 'http://127.0.0.1:7890'；仅未在驾驶舱设置过时生效，界面设置优先）
 ```
 

package/docs/UPGRADE-NOTES.md

@@ -0,0 +1,93 @@
+# 发版必改清单（版本硬编码核对表）
+
+> 用途：每次升级版本号发布时，逐项核对本清单。共 **2 处必改 + 2 处顺手更新 + 4 处禁止改 + 2 处自动派生**。
+> 忘改必改项的下场：build 直接失败（硬校验已拦截）；历史上 version.ts 漏改导致
+> v0.2.0 全体用户看到"0.1.8→0.2.0"假更新横幅。
+
+---
+
+## 一、必改（2 处，必须严格一致）
+
+| # | 文件 | 位置 | 当前值 | 说明 |
+|---|---|---|---|---|
+| 1 | [package.json](../package.json) | 第 3 行 `"version": "0.2.1"` | `0.2.1` | npm 发布版本、CI 取版来源 |
+| 2 | [src/version.ts](../src/version.ts) | 第 9 行 `CURRENT_PLUGIN_VERSION = '0.2.1'` | `'0.2.1'` | 运行时版本比较基准（假横幅的教训来源） |
+
+**两处必须同值**。`pnpm run build` 会硬校验（[scripts/build.mjs](../scripts/build.mjs) 的
+`assertVersionConsistency`），不一致直接构建失败——但不要依赖拦截，发版前手动核对。
+
+`lib/` 下同名编译产物（lib/version.js、lib/version.d.ts）**不用手改**：`pnpm run build`
+从 src 重新编译生成。但**必须重新构建**，否则 npm 包里带的还是旧版编译产物（v0.2.0 事故
+的另一半原因：发布时 lib/version.js 是 0.1.8 的旧产物）。
+
+## 二、发版前顺手更新（2 处，示例版本号）
+
+| # | 文件 | 位置 | 说明 |
+|---|---|---|---|
+| 3 | [docs/npm-publish-guide.md](../docs/npm-publish-guide.md) | Q3 示例命令 | 已改为 `<最新版本号>` 占位符（与 README 同策略，发版无需再改） |
+| 4 | [docs/UPGRADE-NOTES.md](../docs/UPGRADE-NOTES.md)（本文件） | 各表格"当前值"列 | 本清单自身的版本对照，发版后更新 |
+
+## 三、禁止写死版本（4 处，用了占位符/常量——不要往里填具体数字）
+
+| # | 文件 | 位置 | 现状 | 为什么不能填死 |
+|---|---|---|---|---|
+| 5 | [README.md](../README.md) | 第 67 行 `dsh-github-flow@<最新版本号>` | 占位符 | 每次发版都改会漏；占位符引导用户自己查最新版 |
+| 6 | [README.en.md](../README.en.md) | 第 67 行 `dsh-github-flow@<latest-version>` | 占位符 | 同上（英文版） |
+| 7 | [src/updater.ts](../src/updater.ts) | 所有 `CURRENT_PLUGIN_VERSION` 引用 | 常量引用 | 全部从 version.ts 导入，无一硬编码——升级只改 version.ts 一处即全局生效 |
+| 8 | [src/commands/gh.ts](../src/commands/gh.ts) | `/gh status`、`/gh upgrade` 输出 | 常量引用 | 同上 |
+
+## 四、自动派生（2 处，无需手动改，了解即可）
+
+| # | 机制 | 说明 |
+|---|---|---|
+| 9 | CI 取版（.github/workflows/npm-publish.yml:62） | `VERSION=$(node -p "require('./package.json').version")`——从 package.json 读，无硬编码 |
+| 10 | Git tag | `git tag v0.2.1` 手动打，值必须 = package.json 版本（tag 与 package.json 不一致时：CI 发布的 npm 版本以 package.json 为准，GitHub Release 标题以 tag 为准，出现两者错位） |
+
+## 五、发版完整流程（含版本修改）
+
+```powershell
+# 1. 改版本（两处同值）
+#    package.json  → "version": "0.2.1"
+#    src/version.ts → CURRENT_PLUGIN_VERSION = '0.2.1'
+
+# 2. 文档已用占位符（npm-publish-guide 示例、README 安装命令），发版无需改文档版本号
+
+# 3. 构建（版本一致性校验在此拦截漏改）+ 全量测试
+pnpm run build
+pnpm test    # 9 阶段全绿
+
+# 4. 本机 e2e（必须先重启 DSH 桌面进程——Node 模块缓存，软链重建不注入运行中进程）
+#    重启后验证：GET /api/github/check-update 的 currentVersion = 0.2.1
+
+# 5. 提交 + 打 tag + 推送（tag 值 = package.json 版本）
+git add -A
+git commit -m "chore(release): v0.2.1"
+git tag v0.2.1
+git push origin master --tags
+#    CI（npm-publish.yml）自动：构建→发布 npm→创建 GitHub Release
+
+# 6. 发布后 24h 内：用户裸名安装会被 pnpm 供应链锁降级到上一版，
+#    README 占位符已引导显式指定版本，无需额外动作
+```
+
+## 六、历史事故对照（为什么有本清单）
+
+| 事故 | 根因 | 现有防线 |
+|---|---|---|
+| v0.2.0 假更新横幅（全体用户） | src/version.ts 停留 0.1.8，package.json 已 0.2.0；且发布时 lib/version.js 是旧编译产物 | build.mjs 硬校验两处一致；本清单第一、二节 |
+| 0.1.8 幽灵版本（本机 GUI） | DSH 进程模块缓存，重建软链不更新运行中进程 | 流程第 4 步强制重启验证 |
+| tag 与 npm 版本错位风险 | CI 以 package.json 为准、Release 标题以 tag 为准 | 第五节流程强调 tag = package.json |
+| pr checks 完全不可用（Issue #3） | 字段集混入 REST API 字段名（conclusion/detailsUrl），gh 从未支持 | 测试写死合法九字段基准清单（phase1）；新增 --json 字段时对照 `gh <cmd> --json zzz` 错误提示核对 |
+| 无 gh 环境刷新永久卡死 | 前端数据链路 fetch 无 AbortController，代理劫持回环时挂起 | 全部数据 fetch 绑 signal（phase7 第 8 节锚点）；新增前端 fetch 必须带 signal 或显式超时 |
+
+## 七、环境陷阱速查（升级验证时必读）
+
+| 陷阱 | 现象 | 对策 |
+|---|---|---|
+| DSH 进程模块缓存 | 升级/重建后行为不变（幽灵旧版） | 重启 DSH 桌面进程再验证 |
+| execFile input 失效（本机 node 22.18） | stdin 命令挂到超时 | 已用 spawnWithStdin；回归前先跑最小复现 |
+| 交互终端管道继承 | open_terminal 响应挂 10s+ | 已用 stdio:'ignore'；勿改回 execFile |
+| 系统代理劫持回环 | 前端 fetch 永久挂起 | 所有数据链路 fetch 带 signal；文案引导查代理 bypass |
+| 沙箱解除后的测试盲区 | EPERM SKIP 分支掩盖真实缺陷 | CI/真机全绿 ≠ 本机沙箱绿；phase3/5 曾双双漏检 |
+| gh --json 字段集漂移 | Unknown JSON field 直接报错 | 新增字段前用 `gh <cmd> --json zzz` 探测合法集；不跨域复制字段名（checks≠run） |
+| PowerShell 5.1 默认策略 | 唤起终端报 profile 禁止运行红错 | 唤起命令带 -NoProfile（Windows 自带基线优先） |

package/docs/architecture.md

@@ -21,8 +21,9 @@
 │     │   - checkAuth(cwd)      - getRepoMetadata(cwd)               │        │
 │     │   - run<T>(args, opts)  [execFile 数组隔离 + 24KB 智能截断]     │        │
 │     │                                                              │        │
-│     │   - UpdateChecker (双源极速探测 + 24h 缓存 + Fail-Safe)        │        │
+│     │   - UpdateChecker (源可选探测 + 24h 缓存 + Fail-Safe)        │        │
 │     │   - UpgradeManager (跨平台自适应 + 互斥锁 + macOS PATH 补全)   │        │
+│     │   - spawnWithStdin (密文通道: spawn+stdin.end + kill 超时)   │        │
 │     └──────┬───────────────────────┬────────────────────────┬──────┘        │
 │            │                       │                        │               │
 │            ▼                       ▼                        ▼               │
@@ -32,12 +33,12 @@
 │  │  - pr            │    │  /gh upgrade     │    │ - /api/github/overview│  │
 │  │  - issue         │    │  /gh help        │    │ - /api/github/action  │  │
 │  │  - run           │    └──────────────────┘    │ - /api/github/refresh │  │
-│  │  - repo          │                            │ - /check-update (闲时)│  │
+│  │  - repo          │                            │ - /check-update (并行)│  │
 │  │  - api (逃生门)  │                            │ - /upgrade (一键自动) │  │
-│  │  - release       │                            └──────────┬────────────┘  │
-│  │  - secret (stdin)│                                       │               │
-│  │  - skill         │                                       │ HTTP API      │
-│  │  - help (元指南) │                                       │               │
+│  │  - release       │                            │ - /update-settings    │  │
+│  │  - secret (stdin)│                            │ - /proxy (全局代理)   │  │
+│  │  - skill         │                            │ - /auth (轻量探针)    │  │
+│  │  - help (元指南) │                            └──────────┬────────────┘  │
 │  └────────┬─────────┘                                       │               │
 │           │                                                 │               │
 │           ▼                                                 │               │
@@ -60,7 +61,9 @@
 │   │   - 用户提单 / 分配待办 / 我发起 │    │  - 快捷操作网格 (直达入口)   │   │
 │   │   - 顶部升级通知横幅 (Banner)    │    │  - 紧凑微型升级指示条       │   │
 │   │   - 动态数据新鲜度胶囊与 SWR 缓存│    │  - 本地快照胶囊 (对齐规则)  │   │
-│   │   - 数据同步设置弹窗 (Modal)     │    │                             │   │
+│   │   - 四分区设置弹窗 (同步/代理/   │    │  - ⚙️ 完整设置入口 (复用    │   │
+│   │     更新源/关于)                │    │     主页同一弹窗组件)       │   │
+│   │   - 「插件」身份徽章 (关于直达)  │    │  - 「插件」身份徽章 (直达)  │   │
 │   └──────────────────────────────────┘    └─────────────────────────────┘   │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
@@ -87,7 +90,7 @@
 
 ### 2.3.1 高危操作确认与敏感值安全通道 (Safety Confirmation & Secret stdin Channel)
 - 不可逆写操作（`merge` / `close` / `release delete` / clobber 覆盖上传 / `secret delete` / `skill install`）强制要求 `confirm: true` 显式参数，未确认时仅返回影响评估卡片，不产生任何远端或本地副作用；
-- 密钥明文仅经子进程标准输入传递（`execFile` 的 `input` 选项），全程不出现在命令行参数、进程列表与工具输出中；渲染层对 secret 输出采用独立实现，从结构上隔离「绝不渲染 value 字段」这条安全红线。
+- 密钥明文仅经子进程标准输入传递（`spawnWithStdin` 通道：`spawn` + `stdin.end(data)` 半关闭写入——`execFile` 的 `input` 选项在实测环境从不真正写入管道，密文通道此前从未生效过），全程不出现在命令行参数、进程列表与工具输出中；渲染层对 secret 输出采用独立实现，从结构上隔离「绝不渲染 value 字段」这条安全红线。
 
 ### 2.4 原生浅色/深色主题自适应与快捷操作网格
 - 全面对齐 DSH 官方 DSW 语义设计变量，基于 `body[data-ds-dark-theme]` 驱动无闪烁双模式切换；
@@ -114,12 +117,15 @@
 - **双端视图无缝打标**：驾驶舱提供四态响应式药丸筛选（全部/用户提单/指派待办/我发起的），右侧栏直接常驻展现当前工作区所属 Issue 任务清单与状态徽章。
 
 ### 2.8 智能版本检测与跨平台一键升级引擎 (Update & Upgrade Engine)
-- **业务优先与闲时解耦**：
-  - 核心业务接口 `/overview` 仅读取内存缓存，耗时 0ms，绝不阻塞首屏；
-  - 前端在 gh 数据完全加载就绪后，延迟 1.5 秒通过 `requestIdleCallback` 触发独立更新探针 `/check-update`，对主流程零干扰。
-- **国内双 Registry 极速容灾**：
-  - 默认第一顺位请求国内淘宝镜像 `https://registry.npmmirror.com`（2.5 秒超短超时，50~150ms 响应）；
-  - 失败时自动静默回退官方 npmjs 兜底，并支持配置私有源；网络故障 100% Fail-Safe 吸收。
+- **检查与 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`）；
@@ -138,10 +144,19 @@
 - **透明数据新鲜度与状态胶囊 (SyncStatusBadge)**：
   - 胶囊状态精准映射：`[⏳ 后台同步中...]`、`[✅ 已是最新 (15:30)]`、`[📦 本地快照 (X分钟前)]`、`[⚠️ 同步超时已保留缓存]`；
   - 支持人性化相对时间推导（刚刚、X分钟前、X小时前、X天前），消除用户对数据时效性的疑虑。
-- **全景驾驶舱偏好设置面板 (GlobalSyncSettingsModal)**：
-  - **三态刷新模式自主选择**：`⚡ 秒开模式 (SWR, 默认)`、`📋 仅手动刷新 (Manual Only)`、`⏱️ 定时自动轮询 (Auto Poll)`；
-  - **自定义后台轮询周期**：提供 1m / 5m / 15m / 30m / 1h 多档位配置；
-  - **快照容量透明与一键重置**：展示本地快照体积与保存时间戳，支持一键清空重置。
+- **设置中心 (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）等自愈出口。
 

package/docs/npm-publish-guide.md

@@ -45,14 +45,21 @@
 
 ### 1.3 自动发布操作三步走 (发布新版本日常流程)
 
-配置好上述 Secret 后，日常发布新版本只需在本地终端运行：
+配置好上述 Secret 后，日常发布新版本只需在本地终端运行（完整清单见 [UPGRADE-NOTES.md](./UPGRADE-NOTES.md) 发版必改核对表）：
 
 ```bash
-# 第一步：递增版本号（自动修改 package.json 并生成对应 git commit 和 git tag）
+# 第一步：递增版本号——两处必须同步改（package.json + src/version.ts）！
+#   ⚠️ npm version patch 只改 package.json，src/version.ts 需手动同步，
+#   否则 pnpm run build 的版本一致性硬校验会直接失败（v0.2.0 假横幅事故的防线）
 npm version patch   # 修补 Bug: 0.1.0 -> 0.1.1
 # 或者 npm version minor # 新增特性: 0.1.0 -> 0.2.0
+#   （随后编辑 src/version.ts 的 CURRENT_PLUGIN_VERSION 为同值）
 
-# 第二步：将代码与标签推送到 GitHub
+# 第二步：构建 + 全量测试（版本校验在此拦截漏改）
+pnpm run build
+pnpm test
+
+# 第三步：将代码与标签推送到 GitHub（tag 值必须 = package.json 版本）
 git push origin master --tags
 ```
 
@@ -99,6 +106,10 @@ npm publish --access public
 - **原因**：当前打 tag 的代码版本在 `package.json` 中的 `version` 已经被发布过了。
 - **解法**：本地执行 `npm version patch` 递增版本号后再重新打 tag 推送。
 
+### Q2.5: 本地构建报「版本号不一致: package.json=..., src/version.ts=...」
+- **原因**：`npm version` 只更新 package.json，`src/version.ts` 的 `CURRENT_PLUGIN_VERSION` 漏改。
+- **解法**：同步修改 `src/version.ts` 为相同版本后重新构建。这是防「假更新横幅」的硬校验（历史事故：v0.2.0 发布时 version.ts 停留 0.1.8，全体用户被假横幅轰炸）。
+
 ### Q3: 刚发布了新版本（npm 与淘宝镜像均已更新），为什么用户执行 `dsh plugin add` 依然安装了旧版本？
 - **原因**：**触发了 DSH 底层 pnpm 的供应链安全最小发布年龄保护机制（`minimum-release-age`）**。
   1. DSH 内置的包管理器（pnpm）默认启用了防供应链投毒与恶意包抢跑的防御机制，默认配置规则为 `minimum-release-age = 24 * 60`（即 24 小时 / 1 天）；
@@ -107,6 +118,6 @@ npm publish --access public
 - **解法**：
   1. **立即尝鲜安装最新版**：在命令末尾**显式指定目标版本号**（pnpm 会判定为开发者显式信任指定版本，将其加入 `minimumReleaseAgeExclude` 白名单并成功安装）：
      ```powershell
-     dsh plugin --profile desktop add dsh-github-flow@0.1.8
+     dsh plugin --profile desktop add dsh-github-flow@<最新版本号>
      ```
   2. **自然解禁**：新版本在 npm 上的发布时间达到 24 小时后，安全锁定期自动解除，届时所有用户直接运行裸名安装命令均会默认解析安装最新版。

package/lib/api/routes-actions.d.ts

@@ -1,9 +1,23 @@
-/**
- * 动作类路由：缓存强制刷新 + 右侧栏快捷操作（create_pr/create_issue/open_browser/open_terminal）。
- * 共同特征：POST 触发、读少写多、无缓存语义，与概览类路由的演进方向不同。
- */
 import type { GhExecutor } from '../executor.js';
 import { TtlCache } from '../cache.js';
 import type { GitHubOverviewData, GlobalOverviewData } from '../types.js';
 import { type RouteDeps } from './route-helpers.js';
+/**
+ * 构造「在新终端窗口运行命令」的平台命令（execFile 数组形态，不经 shell）。
+ *
+ * Issue #2 修复要点：
+ * - Windows：cmd.exe（显式 .exe，规避 GUI 父进程 PATH 解析差异）+ start 的窗口标题
+ *   占位 "DSH GitHub"——start 的首个带引号参数会被解析为标题而非程序，占位后
+ *   powershell.exe 才能被稳定识别为目标程序；
+ * - macOS：osascript 驱动 Terminal.app，命令经引号转义拼入 AppleScript；
+ * - Linux：发行版终端二进制与参数形态各异（gnome-terminal 用 `--`、konsole 用
+ *   `-e`、xfce4-terminal 用 `-x`），单一硬编码在主流桌面大概率不存在——由
+ *   detectLinuxTerminal 按探测结果返回对应形态。
+ */
+export declare function buildTerminalCommand(command: string): {
+    bin: string;
+    args: string[];
+} | null;
+/** 测试辅助：重置 Linux 终端探测缓存（便于单测注入不同探测环境） */
+export declare function resetLinuxTerminalCache(): void;
 export declare function registerActionRoutes(deps: RouteDeps, executor: GhExecutor, cacheMap: TtlCache<GitHubOverviewData>, globalCache: TtlCache<GlobalOverviewData>): void;