dsh-github-flow 0.2.0 → 0.3.0

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)**:  
@@ -72,7 +72,7 @@ pnpm dsh plugin add dsh-github-flow
 
 ## 🤖 Core Agent Tools: Equipping Agents with Native GitHub Powers
 
-Consolidates scattered GitHub endpoints into **9 core domain tools**, featuring **Token Budget Protection (default 24KB intelligent truncation)**, **High-density Native Markdown Rendering (70%+ list output token reduction)** and **Zero-argument CWD auto-binding**.
+Consolidates scattered GitHub endpoints into **9 core domain tools (76+ actions covering PR/Issue/Actions workflow governance/clone-free file reads/secrets & variables)**, featuring **Token Budget Protection (default 24KB intelligent truncation)**, **High-density Native Markdown Rendering (70%+ list output token reduction)** and **Zero-argument CWD auto-binding**.
 
 ### 1. `github_pr`: Pull Request Lifecycle & Automated Code Review
 > **Example Agent Prompts**:
@@ -85,12 +85,16 @@ 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`);
+  * `ready`: 🆕 Toggle Draft ↔ Ready (`undo: true` converts back to Draft — fully reversible);
+  * `revert`: 🆕 Create a revert commit (generates a new revert PR on the remote; requires `confirm: true`);
+  * `update_branch`: 🆕 Sync the latest base-branch commits into the PR branch — the self-healing action for "branch is out-of-date" CI gate failures;
+  * `view_images`: 🆕 Download PR discussion screenshots (body + comments; `image_urls` targeting with budget-overflow resume list).
 
 ---
 
@@ -105,6 +109,10 @@ Consolidates scattered GitHub endpoints into **9 core domain tools**, featuring
   * `list`: View recent workflow runs and conclusions (`branch` / `status: failure` filters to pin down broken builds);
   * `view`: Inspect jobs and steps for a specific run ID;
   * `trigger`: 🆕 Manually dispatch `workflow_dispatch` workflows to verify fixes immediately;
+  * `workflow_list`: 🆕 List workflows (active only by default; `all: true` includes disabled — when diagnosing "why didn't my workflow run", the disabled state itself is the answer);
+  * `workflow_view`: 🆕 Workflow details (locate by name/ID/filename, with recent runs);
+  * `workflow_enable` / `workflow_disable`: 🆕 Toggle workflows (disable explicitly warns "the next trigger will fail silently");
+  * `download`: 🆕 Download build artifacts to a plugin-managed directory (isolated per repo and run, returns file manifest; older gh versions get a security upgrade note);
   * `rerun`: Re-trigger failed CI runs;
   * `cancel`: Cancel in-progress workflows.
 
@@ -124,7 +132,13 @@ 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;
+  * `delete`: 🆕 **Permanently delete** an issue (requires `confirm: true`; the number is gone forever and comments are destroyed — fundamentally different from close, which can be reopened);
+  * `transfer`: 🆕 Transfer an issue to another repository (requires `confirm: true`; original URL 301-redirects, ownership cannot be silently reverted);
+  * `pin` / `unpin`: 🆕 Toggle issue pinning (reversible state flag);
+  * `lock` / `unlock`: 🆕 Lock/unlock conversation (`lock_reason` supports off_topic/resolved/spam/too_heated);
+  * `status`: 🆕 Account-level assigned-issues panel (Assigned / Mentioning sections);
+  * `view_images`: 🆕 Download issue attachment screenshots (body + comments; `image_urls` targeting with resume list).
 
 ---
 
@@ -136,9 +150,13 @@ 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.
+  * `search_repos`: Search open-source GitHub repositories globally;
+  * `search_issues` / `search_prs` / `search_commits`: 🆕 Global search over issues / PRs / commits (qualifiers go inline in the query, e.g. `repo:o/r state:open`; commits require search text);
+  * `read_file`: 🆕 **Clone-free single-file read at any path** (native on gh ≥2.95; older versions auto-degrade to the contents API with an explicit degraded-path note; binary files are rejected with `github_api` guidance);
+  * `read_dir`: 🆕 Clone-free directory listing (dirs first + file sizes, same degradation path).
 
 ---
 
@@ -163,15 +181,17 @@ Consolidates scattered GitHub endpoints into **9 core domain tools**, featuring
 
 ---
 
-### 7. `github_secret`: CI/CD Secrets Management 🆕
+### 7. `github_secret`: CI/CD Secrets & Variables Management 🆕
 > **Example Agent Prompts**:
 > - *"Update the NPM_TOKEN secret for this repository."*
 > - *"Show which secrets are configured for this repo."*
+> - *"Set the DEPLOY_ENV variable to staging and read it back to confirm."*
 
 * **Supported Actions**:
-  * `list`: Show secret names and update times (the GitHub API never exposes secret values);
+  * `list`: Show secret/variable names and update times (the GitHub API never exposes secret values);
   * `set`: Set/update secret values — **passed via subprocess stdin, never on the command line (ps-safe), never echoed in output**;
   * `delete` (requires `confirm: true`): Remove a secret.
+  * Switch to **Actions plaintext variables** via `kind: 'variable'`: `set` passes the value directly as a flag and `get` can echo it back (that's the design difference from secrets — secrets are encrypted GitHub-side after write and physically unreadable); the two security semantics are physically isolated in the rendering layer.
   * Supports repository / organization (`org`) / environment (`env`) scopes across `actions` / `codespaces` / `dependabot` / `agents` apps.
 
 ---
@@ -229,20 +249,30 @@ Access via the GitHub icon in the main left navigation:
 </p>
 
 ### 2. Session Right Sidebar Panel (Workspace Drawer)
-Located in the right drawer of every chat workspace:
-* **Context Auto-Binding**: Automatically locks onto the active Git repository;
-* **Freshness Pill Alignment**: Compact indicator `[📦 Local Snapshot (2m ago)]` with live `[🔄 Refresh]` button, 100% aligned with global rules;
-* **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.
+Located in the right drawer of every chat workspace, seamlessly bridging your local Git workspace with remote GitHub repositories:
+* **Context Auto-Binding**: Automatically locks onto the active Git repository of the current session;
+* **Freshness Pill Alignment**: Compact indicator `[📦 Local Snapshot (2m ago)]` with live `[🔄 Refresh]` button, 100% aligned with global rules for an instant 0ms first render;
+* **Quick Action Grid**: Open repo in browser, jump to Issues/PRs, create PRs with one click;
+* **Five Mutually Exclusive Tabs**: Compact tabbed navigation directly below the quick action grid, reducing vertical scrolling:
+  * **Git Records (`Git`)** (Default tab):
+    * Branch & Remote Sync: Real-time branch indicator (e.g. `master`) with tracking sync status (`✓ Up to date` or `↑N to push` / `↓N to pull`);
+    * Three-Section Commit View: Unpushed commits (ahead of remote), unpulled commits (behind remote), and recent commit history;
+    * 15 commits displayed by default, with **infinite scroll loading** when scrolling to the bottom (with live `15 / 74` progress counter and click trigger);
+    * Latest Release badge (`🏷️ v0.2.1`) anchored in the top right with hover details and direct release link;
+    * **Commit Detail Modal**: Click any commit row to open a clean modal dialog centered within the right sidebar (scoped inside drawer boundaries without overflowing full-screen), featuring smooth vertical scrolling, full 40-char SHA, author email, date, multi-line commit message body, and file diff stat table (`--stat`); pure local 0ms instant display, closable via `Esc`, close button, or backdrop click;
+  * **Uncommitted Changes (`📁 Uncommitted (N)`)**: Full-width list of uncommitted files with color-coded status codes (`??` untracked, `M` modified, `D` deleted, `R` renamed) and change counts;
+  * **Pull Requests (`🔀 PR (N)`)**: Open PR inspection with 3-state CI check rollup (`✅ CI Passed` / `❌ CI Failed` / `⏳ CI Pending`), merge conflict detection, review decisions (`✔ Approved` / `✋ Changes Requested` / `👀 Review Required`), Draft pills, and humanized relative timestamps;
+  * **Workspace Issues (`📋 Issues (N)`)**: Direct issue task review with assignees, labels, and category pills;
+  * **Actions Pipeline (`⚡ Actions (N)`)**: Real-time CI workflow status tracking with trigger event badges (`push`/`schedule`/`manual`/`PR`), relative time, and self-healing diagnostic notes for failed runs (embedding `run_id` for Agent one-click log inspection);
+* **Official Git Vector Icon**: High-definition Git diamond vector icon (`#1296db` SVG) across all Git and branch labels;
+* **⚙️ Full Settings Access**: Dedicated 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 +288,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 +311,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.
 
@@ -329,6 +374,7 @@ Works out of the box, with optional tweaks in `cordis.patch.yml` or your profile
         defaultListLimit: 20      # Default list size for pr/issue/run/release/skill queries
         cacheTtlMs: 15000         # Repository overview cache TTL (default 15s)
         checkUpdate: true         # Enable automatic update checks (default true)
+        agentEnvInjection: true   # Inject AI_AGENT=dsh identity into gh (auto agent-friendly output on gh ≥2.99; false restores native gh behavior)
         updateCheckIntervalMs: 86400000 # Check interval in ms (default 24h)
         registryUrl: ''           # Custom private npm registry URL
         proxyUrl: ''              # Preset proxy default (e.g. 'http://127.0.0.1:7890'; only applies before the cockpit setting is saved — UI setting takes precedence)

package/README.md

@@ -10,7 +10,7 @@
 
 <p align="center">
   <b>让 DeepSeek Harness Agent 拥有操作 GitHub 的原生手和脚，为人机协作打造沉浸式 GitHub 工作台。</b><br>
-  原生复用宿主机 <code>gh</code> CLI 安全登录凭据，告别 Personal Access Token 泄露；深度打通本地 Git 工作区与云端仓库协作，兼具 <b>9 大领域 Agent 核心工具</b>、<b>人类 Slash 快捷指令</b>、<b>Web UI 全景工作台</b> 与 <b>一键自动跨平台无缝升级</b>。
+  原生复用宿主机 <code>gh</code> CLI 安全登录凭据，告别 Personal Access Token 泄露；深度打通本地 Git 工作区与云端仓库协作，兼具 <b>9 大领域 Agent 核心工具（76+ action，覆盖 PR/Issue/Actions 工作流治理/免 clone 读取任意文件/密钥与变量管理）</b>、<b>人类 Slash 快捷指令</b>、<b>Web UI 全景工作台</b> 与 <b>一键自动跨平台无缝升级</b>。
 </p>
 
 <p align="center">
@@ -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,16 @@ 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` 二次确认）；
+  * `ready`：🆕 Draft ↔ Ready 切换（附 `undo: true` 可转回 Draft，完整可逆）；
+  * `revert`：🆕 创建反向提交（远端生成新 revert PR，需 `confirm: true`）；
+  * `update_branch`：🆕 将基准分支最新提交同步进 PR 分支——「分支落后需更新」CI 门禁失败的自愈动作；
+  * `view_images`：🆕 下载 PR 讨论截图（正文+评论，支持 `image_urls` 精准提取与触顶续传清单）。
 
 ---
 
@@ -105,6 +109,10 @@ pnpm dsh plugin add dsh-github-flow
   * `list`：查看当前仓库的 Workflow 运行历史与结论（支持 `branch` / `status: failure` 快速锁定失败构建）；
   * `view`：查看指定 run_id 的详细阶段（Jobs & Steps）；
   * `trigger`：🆕 主动触发 `workflow_dispatch` 工作流（提交修复后立即验证远端 CI）；
+  * `workflow_list`：🆕 工作流清单查询（默认仅 active；`all: true` 含 disabled——排查「工作流为何不跑」时 disabled 状态本身就是答案）；
+  * `workflow_view`：🆕 工作流详情（名称/ID/文件名定位，含最近运行记录）；
+  * `workflow_enable` / `workflow_disable`：🆕 启停工作流（disable 会显式警告「下次 trigger 将静默失败」）；
+  * `download`：🆕 下载构建产物到插件管理目录（按仓库与 run 隔离，返回文件清单；低版本 gh 附安全升级提示）；
   * `rerun`：重新触发失败的 CI 运行；
   * `cancel`：取消在途的工作流。
 
@@ -124,7 +132,13 @@ pnpm dsh plugin add dsh-github-flow
   * `edit`：🆕 修改标题、正文与增删标签；
   * `develop`：🆕 从 Issue 一键切出关联开发分支并本地检出，打通「读需求 → 写代码」闭环；
   * `comment`：在指定 Issue 中追加排查进展或评论；
-  * `close`（需 `confirm: true`）/ `reopen`：开启或关闭 Issue。
+  * `close`（需 `confirm: true`）/ `reopen`：开启或关闭 Issue；
+  * `delete`：🆕 **物理删除** Issue（需 `confirm: true`；编号永久消失、评论湮灭不可恢复——与 close 可 reopen 有本质区别，拦截级别更高）；
+  * `transfer`：🆕 跨仓库迁移 Issue（需 `confirm: true`；原 URL 301 重定向，归属不可静默撤回）；
+  * `pin` / `unpin`：🆕 置顶/取消置顶（可逆状态位）；
+  * `lock` / `unlock`：🆕 锁定/解锁对话（`lock_reason` 支持 off_topic/resolved/spam/too_heated）；
+  * `status`：🆕 账号维度的分配议题面板（Assigned / Mentioning 分段）；
+  * `view_images`：🆕 下载 Issue 报障截图（正文+评论全量提取，支持 `image_urls` 按 URL 精准提取，触顶自动返回续传清单）。
 
 ---
 
@@ -136,9 +150,13 @@ pnpm dsh plugin add dsh-github-flow
 
 * **支持操作 (`action`)**：
   * `view`：查看当前或目标仓库的元数据（默认分支、星标、描述、Topics 与开源协议）；
+  * `readme`：🆕 读取仓库 README 原文（支持指定分支，相对路径截图自动解析下载）；
   * `sync`：🆕 一键拉平 Fork 仓库与上游主干，解决贡献开源项目时 Fork 落后导致 CI 门禁失败；
   * `search_code`：跨仓库或当前仓库检索特定代码符号；
-  * `search_repos`：跨全站检索 GitHub 开源仓库。
+  * `search_repos`：跨全站检索 GitHub 开源仓库；
+  * `search_issues` / `search_prs` / `search_commits`：🆕 全站检索 Issue / PR / 提交记录（限定符直接写进 query，如 `repo:o/r state:open`；commits 必须含搜索文本）；
+  * `read_file`：🆕 **免 clone 读取任意路径单文件**（gh ≥2.95 直连，低版本自动降级 contents API 并显式标注降级链路；二进制文件拒绝并引导 `github_api`）；
+  * `read_dir`：🆕 免 clone 列出目录清单（dir 置顶 + 文件大小，降级链路同上）。
 
 ---
 
@@ -163,15 +181,17 @@ pnpm dsh plugin add dsh-github-flow
 
 ---
 
-### 7. `github_secret`：CI/CD 部署密钥安全管理 🆕
+### 7. `github_secret`：CI/CD 密钥与变量管理 🆕
 > **典型对话指令**：
 > - *"帮我把新的 NPM_TOKEN 更新到当前仓库的 Secrets 里"*
 > - *"看一下这个仓库配了哪些密钥"*
+> - *"把 DEPLOY_ENV 变量设为 staging，并回读确认"*
 
 * **支持操作 (`action`)**：
-  * `list`：查看密钥名称清单（仅名称与更新时间，GitHub API 设计上不允许读取密文）；
+  * `list`：查看密钥/变量名称清单（仅名称与更新时间，GitHub API 设计上不允许读取密文）；
   * `set`：设置/更新密钥值——**密文经子进程标准输入传递，绝不出现在命令行参数（防 `ps` 窃取），输出永不回显**；
   * `delete`（需 `confirm: true`）：删除密钥。
+  * 支持 `kind: 'variable'` 切换到 **Actions 明文变量**：`set` 走参数直传、`get` 可回显值（这正是变量与密钥的设计区别——secret 写入后 GitHub 侧加密，物理不可读取）；两类对象的安全语义在渲染层物理隔离。
   * 支持仓库 / 组织 (`org`) / 环境 (`env`) 三级作用域与 `actions` / `codespaces` / `dependabot` / `agents` 应用归属。
 
 ---
@@ -228,20 +248,30 @@ pnpm dsh plugin add dsh-github-flow
 </p>
 
 ### 2. 会话右侧栏工作区面板 (Session Workspace Panel)
-位于每个对话工作区的右侧抽屉栏：
-* **当前仓库上下文绑定**：自动锁定当前会话的 Git 仓库，无需选择；
+位于每个对话工作区的右侧抽屉栏，深度联动本地 Git 状态与远程 GitHub 仓库：
+* **当前仓库上下文绑定**：自动锁定当前会话的物理 Git 仓库，展示远程关联与认证账号；
 * **数据新鲜度胶囊对齐**：标题旁紧凑呈现 `[📦 本地快照 (2分钟前)]` 与 `[🔄 刷新]` 按钮，与主页规则 100% 保持一致，首屏 0ms 瞬间直出；
-* **PR 门禁状态药丸**：展示当前开放 PR，悬停查看 Checks 结果与审核意见；
-* **当前仓库 Open Issues 列表**：直接在侧边栏审查待办任务并提供直达链接；
-* **最新 Actions 构建流水线**：实时关注 CI 状态；
-* **快捷操作网格**：一键在浏览器打开仓库、直达 Issues/PRs、一键创建 PR。
+* **快捷操作网格**：一键在浏览器打开仓库、直达 Issues/PRs、一键创建 PR；
+* **五大 Tab 布局响应式互斥切换**：快捷操作下方采用紧凑 Tab 架构，内容区互斥展示、大幅降低纵向滚动需求：
+  * **Git 记录 (`Git`)**（默认首屏）：
+    * 分支与同步状态：展示当前分支（如 `master`）与远程同步快照（`✓ 与远程同步` 或 `↑N 待 push` / `↓N 待 pull`）；
+    * 三段式提交视图：待推送提交（本地领先）、待拉取提交（远程领先）及最近提交列表；
+    * 默认展示 15 条，支持**向下滑动触底自动分页加载**（伴随 `15 / 74` 实时进度提示与点击后备）；
+    * 右上角锚定最新发布 Release 徽章（`🏷️ v0.2.1`），悬停查看发布时间与预发布标示，点击直达；
+    * **提交详情模态弹窗**：点击任意提交记录行，在右侧栏内局部居中弹出（与设置弹窗同构，不全屏越界），内置上下滑动区域，完整展示 40 位 SHA、提交者姓名邮箱、日期、多行详细正文说明与文件变更统计（`--stat`），纯本地 0ms 秒开，支持按 `Esc` 或点击遮罩随时关闭；
+  * **未提交清单 (`📁 未提交 (N)`)**：展示工作区未提交的文件清单，状态码色彩区分（`??` 新增、`M` 修改、`D` 删除、`R` 重命名）与变更总数；
+  * **拉取请求 (`🔀 PR (N)`)**：展示当前开放 PR，带有三态 CI 门禁（`✅ CI 通过` / `❌ CI 失败` / `⏳ CI 运行中`）、冲突检测、审核判定（`✔ 已批准` / `✋ 需修改` / `👀 待审查`）、Draft 草稿标示与人性化相对时间；
+  * **仓库议题 (`📋 Issues (N)`)**：直接在侧边栏审查待办任务，支持指派者、标签与多维状态药丸；
+  * **构建流水线 (`⚡ Actions (N)`)**：实时关注工作流 CI 状态，展示触发方式（`push`/`定时`/`手动`/`PR`）、相对时间与失败构建的 Agent 自愈诊断指引（嵌入 run_id）；
+* **全库统一 Git 官方矢量图标**：采用标准 Git 菱形分支官方矢量组件（`#1296db` SVG），全面统一各处 Git 标识；
+* **⚙️ 完整设置入口**：右侧栏提供设置按钮，与主页复用同一设置弹窗（数据同步 / 网络代理 / 更新设置 / 关于 四分区完整可用），无需切回主页调整。
 
 <p align="center">
   <img src="./docs/images/2.png" alt="右侧栏工作区面板" width="100%" />
 </p>
 
 ### 3. 设置中心 (Settings Modal)
-点击全景驾驶舱右上角 **`[⚙️ 设置]`** 打开分区式设置弹窗，左侧分区导航、右侧内容独立滚动（窄屏自动折叠为横向页签）：
+点击全景驾驶舱右上角 **`[⚙️ 设置]`**（或右侧栏的 ⚙️ 按钮）打开分区式设置弹窗，左侧分区导航、右侧内容独立滚动（窄屏自动折叠为横向页签）：
 
 **🔄 数据同步分区**——调优数据拉取节奏：
 * **两种同步策略**：
@@ -257,6 +287,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 +310,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 +372,10 @@ 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 时熔断自动探测，显式升级不受限）
+        agentEnvInjection: true   # 向 gh 注入 AI_AGENT=dsh 识别信号（gh ≥2.99 自动适配 Agent 输出；false 恢复 gh 原生行为）
         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.3.0"` | `0.3.0` | npm 发布版本、CI 取版来源 |
+| 2 | [src/version.ts](../src/version.ts) | 第 9 行 `CURRENT_PLUGIN_VERSION = '0.3.0'` | `'0.3.0'` | 运行时版本比较基准（假横幅的教训来源） |
+
+**两处必须同值**。`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.3.0` 手动打，值必须 = package.json 版本（tag 与 package.json 不一致时：CI 发布的 npm 版本以 package.json 为准，GitHub Release 标题以 tag 为准，出现两者错位） |
+
+## 五、发版完整流程（含版本修改）
+
+```powershell
+# 1. 改版本（两处同值）
+#    package.json  → "version": "0.3.0"
+#    src/version.ts → CURRENT_PLUGIN_VERSION = '0.3.0'
+
+# 2. 文档已用占位符（npm-publish-guide 示例、README 安装命令），发版无需改文档版本号
+
+# 3. 构建（版本一致性校验在此拦截漏改）+ 全量测试
+pnpm run build
+pnpm test    # 11 阶段全绿
+
+# 4. 本机 e2e（必须先重启 DSH 桌面进程——Node 模块缓存，软链重建不注入运行中进程）
+#    重启后验证：GET /api/github/check-update 的 currentVersion = 0.3.0
+
+# 5. 提交 + 打 tag + 推送（tag 值 = package.json 版本）
+git add -A
+git commit -m "chore(release): v0.3.0"
+git tag v0.3.0
+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 自带基线优先） |