dsh-github-flow 0.1.8 → 0.2.1

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>5 大领域 Agent 核心工具</b>、<b>人类 Slash 快捷指令</b>、<b>Web UI 全景工作台</b> 与 <b>一键自动跨平台无缝升级</b>。
+  原生复用宿主机 <code>gh</code> CLI 安全登录凭据，告别 Personal Access Token 泄露；深度打通本地 Git 工作区与云端仓库协作，兼具 <b>9 大领域 Agent 核心工具</b>、<b>人类 Slash 快捷指令</b>、<b>Web UI 全景工作台</b> 与 <b>一键自动跨平台无缝升级</b>。
 </p>
 
 <p align="center">
@@ -34,9 +34,45 @@
 
 ---
 
+## 🚀 安装指南
+
+### 步骤 1：前置准备（若已安装可跳过）
+确保你的机器上已安装 GitHub CLI (`gh`) 并已登录：
+```bash
+# Windows 安装
+winget install --id GitHub.cli
+
+# macOS 安装
+brew install gh
+
+# 登录认证（仅需执行一次）
+gh auth login
+```
+
+### 步骤 2：安装插件到 DSH
+
+在 DSH 终端根据你的使用环境执行对应命令：
+
+```bash
+# 场景 A：DSH 桌面版 (Desktop Profile)
+dsh plugin --profile desktop add dsh-github-flow
+
+# 场景 B：DSH Web / CLI 环境（--profile 为官方 CLI 必填参数，profile 名按实际环境填写）
+dsh plugin --profile web add dsh-github-flow
+```
+
+> 💡 **提示（新版本发布后 24 小时内的安全锁定期说明）**：  
+> DSH 内置包管理器默认启用了防投毒的供应链安全策略（`minimum-release-age = 24h`）。新版本发布后的 **24 小时内**，若执行不带版本号的裸名安装命令，底层会自动回退为发布满 24 小时的上一稳定版本。如需**立即尝鲜刚发布的新版本**，请在命令末尾显式追加 `@版本号`（替换为 npm 页面显示的最新版本）：
+> ```bash
+> dsh plugin --profile desktop add dsh-github-flow@<最新版本号>
+> ```
+> 版本发布满 24 小时后，执行原本的裸名命令即可默认解析安装最新版。
+
+---
+
 ## 🤖 核心工具集 (Agent Tools)：给 Agent 装上 GitHub 的手和脚
 
-本插件精选聚合为 **5 大领域核心工具**，拒绝几十个无用微型工具撑爆 Agent 上下文，原生搭载 **Token 防溢出保护（默认 24KB 智能二分截断）** 与 **零参数 CWD 智能绑定**。
+本插件精选聚合为 **9 大领域核心工具**，拒绝几十个无用微型工具撑爆 Agent 上下文，原生搭载 **Token 防溢出保护（默认 24KB 智能二分截断）**、**高密度 Markdown 原生渲染（列表输出压缩 70%+ Token）** 与 **零参数 CWD 智能绑定**。
 
 ### 1. `github_pr`：PR 全生命周期管理与自动化代码审查
 > **典型对话指令**：
@@ -46,13 +82,16 @@
 > - *"检查 PR #8 的 CI 检查通过了吗？通过的话帮我 Squash 合并并删除源分支"*
 
 * **支持操作 (`action`)**：
-  * `list`：列出当前仓库开放的 PR（带作者、审查判定、CI 门禁状态）；
+  * `list`：列出当前仓库开放的 PR（带作者、审查判定、CI 门禁状态，支持 `state` / `author` / `limit` 过滤）；
   * `view`：查看指定 PR 详情、描述与元数据；
-  * `diff`：获取 PR 的完整代码差异（内置智能防溢出截断保护）；
-  * `checks`：审查指定 PR 的 CI 门禁状态与检查套件结果；
+  * `diff`：获取 PR 的完整代码差异（`stat_only` 仅看文件变更概览，防大 PR 溢出）；
+  * `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`）。
+  * `merge`：自动执行合并（支持 `squash` / `merge` / `rebase`，可指定 `delete_branch`；需 `confirm: true` 二次确认）；
+  * `view_images`：🆕 下载 PR 讨论截图（正文+评论，支持 `image_urls` 精准提取与触顶续传清单）。
 
 ---
 
@@ -64,8 +103,9 @@
 
 * **支持操作 (`action`)**：
   * `log_failed`（🔥 **核心杀手锏**）：**专供 Agent 快速诊断**，自动抓取并剥离无关日志，精准提取失败 Step 的关键错误堆栈，供 Agent 直击问题修复代码；
-  * `list`：查看当前仓库的 Workflow 运行历史与结论；
+  * `list`：查看当前仓库的 Workflow 运行历史与结论（支持 `branch` / `status: failure` 快速锁定失败构建）；
   * `view`：查看指定 run_id 的详细阶段（Jobs & Steps）；
+  * `trigger`：🆕 主动触发 `workflow_dispatch` 工作流（提交修复后立即验证远端 CI）；
   * `rerun`：重新触发失败的 CI 运行；
   * `cancel`：取消在途的工作流。
 
@@ -79,11 +119,14 @@
 > - *"把 Issue #45 关闭"*
 
 * **支持操作 (`action`)**：
-  * `list`：多条件检索 Issue 列表；
+  * `list`：多条件检索 Issue 列表（`state` / `labels` / `assignees` / `limit`）；
   * `view`：查看 Issue 正文与评论历史；
   * `create`：创建新 Issue（支持标题、正文、标签、指派人）；
+  * `edit`：🆕 修改标题、正文与增删标签；
+  * `develop`：🆕 从 Issue 一键切出关联开发分支并本地检出，打通「读需求 → 写代码」闭环；
   * `comment`：在指定 Issue 中追加排查进展或评论；
-  * `close` / `reopen`：开启或关闭 Issue。
+  * `close`（需 `confirm: true`）/ `reopen`：开启或关闭 Issue；
+  * `view_images`：🆕 下载 Issue 报障截图（正文+评论全量提取，支持 `image_urls` 按 URL 精准提取，触顶自动返回续传清单）。
 
 ---
 
@@ -94,7 +137,9 @@
 > - *"查看仓库 cli/cli 的基本信息与星标数"*
 
 * **支持操作 (`action`)**：
-  * `view`：查看当前或目标仓库的元数据（默认分支、星标、描述、Visibility）；
+  * `view`：查看当前或目标仓库的元数据（默认分支、星标、描述、Topics 与开源协议）；
+  * `readme`：🆕 读取仓库 README 原文（支持指定分支，相对路径截图自动解析下载）；
+  * `sync`：🆕 一键拉平 Fork 仓库与上游主干，解决贡献开源项目时 Fork 落后导致 CI 门禁失败；
   * `search_code`：跨仓库或当前仓库检索特定代码符号；
   * `search_repos`：跨全站检索 GitHub 开源仓库。
 
@@ -104,11 +149,72 @@
 > **典型对话指令**：
 > - *"调用 GitHub API 获取当前仓库最新的 Release 列表，用 jq 提取 tag 名称"*
 
-* **核心优势**：直接复用本地认证环境调用任意 REST / GraphQL API，支持 `--jq` 预过滤与 `raw` 原始响应模式，绝不因插件未封装特定接口而受限。
+* **核心优势**：直接复用本地认证环境调用任意 REST / GraphQL API，支持 `--jq` 预过滤、`raw` 原始响应模式与 `paginate` 自动翻页聚合，绝不因插件未封装特定接口而受限。
 
 ---
 
-## 🖥️ 原生 Web UI 沉浸式工作台与同步设置
+### 6. `github_release`：版本发布与构建资产交付 🆕
+> **典型对话指令**：
+> - *"给当前仓库发布 v0.2.0 版本，自动根据提交记录生成发版说明"*
+> - *"把刚打好的 dsh-github-flow-0.2.0.tgz 上传到 v0.2.0 Release"*
+
+* **支持操作 (`action`)**：
+  * `list` / `view`：查看发版历史与任意版本详情（资产清单、发版说明）；
+  * `create`：创建 Release（`generate_notes` 自动生成说明、`draft` / `prerelease` 标记、可直接附带资产）；
+  * `upload` / `download`：上传 `.tgz` 等构建产物或按 glob 下载资产；
+  * `delete`（需 `confirm: true`）：删除 Release，可选连 Tag 一起清理。
+
+---
+
+### 7. `github_secret`：CI/CD 部署密钥安全管理 🆕
+> **典型对话指令**：
+> - *"帮我把新的 NPM_TOKEN 更新到当前仓库的 Secrets 里"*
+> - *"看一下这个仓库配了哪些密钥"*
+
+* **支持操作 (`action`)**：
+  * `list`：查看密钥名称清单（仅名称与更新时间，GitHub API 设计上不允许读取密文）；
+  * `set`：设置/更新密钥值——**密文经子进程标准输入传递，绝不出现在命令行参数（防 `ps` 窃取），输出永不回显**；
+  * `delete`（需 `confirm: true`）：删除密钥。
+  * 支持仓库 / 组织 (`org`) / 环境 (`env`) 三级作用域与 `actions` / `codespaces` / `dependabot` / `agents` 应用归属。
+
+---
+
+### 8. `github_skill`：跨 Agent 开源 Skills 生态发现 🆕
+> **典型对话指令**：
+> - *"在 GitHub 上搜一下有没有关于 code-review 的 Agent Skill"*
+> - *"预览一下那个 Skill 的内容，合适就装到当前项目"*
+
+* **支持操作 (`action`)**：
+  * `search`：基于 GitHub Code Search 跨仓库检索开源 `SKILL.md` 技能（带 Stars 排序）；
+  * `preview`：只读预览 Skill 内容，安装前审阅行为约束，不落盘；
+  * `install`（需 `confirm: true`）：安装到本地 Agent 宿主（Claude Code / Cursor / Copilot 等 50+），支持 `project` / `user` 两种范围；
+  * `list`：查看本机已安装的全部 Skills。
+  * 依赖 GitHub CLI 2.9x+ 的 `gh skill` 官方 preview 特性。
+
+---
+
+### 9. `github_help`：元指南与故障自愈中枢 🆕
+> **典型对话指令**：
+> - *"我不确定该用哪个 GitHub 工具做这件事"*
+> - *"GitHub 搜索的高级语法怎么写？"*
+
+* **核心能力**：
+  * 9 大工具任务路由导航（「什么任务调什么工具」一查便知）；
+  * 官方高级检索语法速查（日期区间、状态修饰符、代码搜索范围限定）；
+  * 常见故障自愈配方（403 限流、422 参数缺失、Fork 落后拉平、CLI 版本过低）；
+  * 直接透传 `gh help <command>` 官方离线手册。
+
+---
+
+## 🛡️ 安全防线设计
+
+* **高危操作双重确认**：`merge`、`close`、`release delete`、覆盖上传 (`clobber`)、`secret delete`、`skill install` 等不可逆或写盘操作强制要求 `confirm: true` 参数；未确认时只返回影响评估报告，绝不执行。杜绝模型幻觉导致的意外合并或删除。
+* **密文标准输入通道**：`github_secret` 的密钥值经子进程 stdin 传递，全程不出现在命令行参数（防 `ps` / 任务管理器窃取）、不落盘、不在输出中回显；gh 在本地用仓库公钥加密后才上传。
+* **命令注入免疫**：所有 gh 调用采用 `execFile` 数组参数隔离执行，零 Shell 字符串拼接。
+
+---
+
+## 🖥️ 原生 Web UI 沉浸式工作台与设置中心
 
 ### 1. 全局全景驾驶舱 (Global Cockpit)
 
@@ -131,53 +237,46 @@
 * **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. 数据同步与缓存偏好设置 (Sync Settings Modal)
-点击全景驾驶舱右上角 **`[⚙️ 同步设置]`** 即可随时调优数据拉取节奏：
-* **三种刷新策略随心选**：
-  * **⚡ 秒开模式 (SWR, 推荐)**：打开驾驶舱立即展示上次本地缓存（0ms秒开），后台静默同步最新状态；
-  * **📋 仅在手动点击时拉取 (Manual Only)**：打开只浏览本地缓存，绝不自动触发后台 gh 进程，最省电、最省资源；
-  * **⏱️ 定时自动轮询 (Auto Poll)**：驾驶舱打开期间，按照设定间隔在后台自动轮询。
-* **自定义后台拉取间隔**：支持选择 1 分钟 / 5 分钟 (默认) / 15 分钟 / 30 分钟 (推荐节能) / 1 小时 / 从不自动刷新；
-* **本地缓存可视化管理**：透明查看本地快照体积与保存时间戳，支持一键 `[🗑️ 清空缓存]` 重置。
-
-<p align="center">
-  <img src="./docs/images/3.png" alt="数据同步与缓存设置弹窗" width="85%" />
-</p>
-
----
-
-## 🚀 安装指南
-
-### 步骤 1：前置准备（若已安装可跳过）
-确保你的机器上已安装 GitHub CLI (`gh`) 并已登录：
-```bash
-# Windows 安装
-winget install --id GitHub.cli
+### 3. 设置中心 (Settings Modal)
+点击全景驾驶舱右上角 **`[⚙️ 设置]`**（或右侧栏的 ⚙️ 按钮）打开分区式设置弹窗，左侧分区导航、右侧内容独立滚动（窄屏自动折叠为横向页签）：
 
-# macOS 安装
-brew install gh
+**🔄 数据同步分区**——调优数据拉取节奏：
+* **两种同步策略**：
+  * **⚡ 秒开模式 (SWR, 推荐)**：打开驾驶舱立即展示上次本地缓存（0ms秒开），并在 300ms 内后台静默同步最新状态——无论缓存多旧，打开即可自愈为最新；
+  * **📋 仅在手动点击时拉取 (Manual Only)**：打开只浏览本地缓存，绝不自动触发后台 gh 进程，最省电、最省资源；想更新时点击「🔄 刷新」即可。
+* **本地缓存可视化管理**：透明查看本地快照体积与保存时间戳，支持一键 `[🗑️ 清空缓存]` 重置。
 
-# 登录认证（仅需执行一次）
-gh auth login
-```
+**🌐 网络代理分区**——让插件全部外联流量走你的代理：
+* **全局生效范围**：设置后驾驶舱、右侧栏面板、9 大 Agent 工具调用与一键升级链路全部经代理访问；未启用时默认使用系统环境代理（`HTTPS_PROXY` 等）或直连；
+* **协议支持**：`http://` / `https://` / `socks5://` / `socks5h://`（gh 与 npm 链路原生支持 SOCKS5；`socks5h` 会把域名解析也交给代理端，抗 DNS 污染更强；npm 版本探测走 Node fetch 暂不支持 SOCKS，将保持直连并在界面如实标注）；
+* **`[🧪 测试连通性]`**：一键探测经当前代理访问 GitHub API 的延迟；
+* **保存即生效**：写入 `~/.dsh/data/dsh-github-flow/proxy.json` 持久化（DSH 重启自动恢复），无需重启、不重载插件；
+* **生效可视化**：代理启用时驾驶舱标题栏显示 `🌐 代理` 徽章，悬停查看当前代理地址；
+* **NO_PROXY 排除列表**：`localhost` 与 `127.0.0.1` 强制包含，本机 Web API 回环请求永不被代理劫持。
 
-### 步骤 2：安装插件到 DSH
+**⬆️ 更新设置分区**——选择新版本检测所用的 npm 源：
+* **三态单选**：🌍 npm 官方源（默认，版本全球首发最及时）/ 🇨🇳 国内镜像 npmmirror（国内访问快，同步存在分钟级延迟）/ ⛔ 不检查更新（仅关闭自动提示横幅，`/gh upgrade` 与一键升级仍可用）；
+* **单源严格不互备**：显式选择的源不会被静默替换——选官方就只查官方，探测失败如实提示而非假装正常；
+* **检测与升级流量遵循全局代理设置**（与网络代理分区联动，socks5 边界在界面如实标注）；
+* **一键升级的安装源跟随选择**：选了镜像源，一键升级也走镜像安装；
+* **保存即验证**：切换源后立即用新源真实探测一次并回显最新版本号。
 
-在 DSH 终端根据你的使用环境执行对应命令：
+**ℹ️ 关于分区**——插件身份与项目信息：
+* 当前运行版本、项目简介、GitHub 仓库地址、npm 包页面与 MIT 开源协议；
+* 求 Star 卡片——如果插件对你的研发有帮助，欢迎到仓库点个 Star 支持持续迭代。
 
-```bash
-# 场景 A：DSH 桌面版 (Desktop Profile)
-dsh plugin --profile desktop add dsh-github-flow
+> 🏷️ **插件身份标识**：全景驾驶舱与右侧栏的标题旁均带有「插件」小徽标，明确标识界面由第三方插件 `dsh-github-flow` 提供（非 DSH / GitHub 官方功能）。点击徽标即可打开「关于」页面查看项目信息。
 
-# 场景 B：DSH Web / CLI 工程环境
-pnpm dsh plugin add dsh-github-flow
-```
+| 🔄 数据同步分区 | 🌐 网络代理分区 |
+| :---: | :---: |
+| ![设置中心·数据同步分区](./docs/images/3.png) | ![设置中心·网络代理分区](./docs/images/4.png) |
 
 ---
 
@@ -185,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 服务以激活后端新工具，也可点击按钮立即刷新页面预览新界面。
 
@@ -206,17 +307,15 @@ pnpm dsh plugin add dsh-github-flow
 首次渲染 (0ms) ──────────> 恢复本地持久化快照，瞬间完整上屏
                                 │
                                 ├── SWR 模式: 延迟 300ms 后台静默拉取，平滑对齐最新数据
-                                ├── 手动模式: 仅浏览本地快照，点击「🔄 刷新」才发起拉取
-                                └── 轮询模式: 按设定间隔 (如 5m/30m) 自动后台轮询
+                                └── 手动模式: 仅浏览本地快照，点击「🔄 刷新」才发起拉取
 ```
 
-### 三种刷新策略对比与选用建议：
+### 两种刷新策略对比与选用建议：
 
 | 刷新模式 | 运行机制 | 适用人群与场景 |
 | :--- | :--- | :--- |
-| **⚡ 秒开模式 (SWR, 默认)** | 打开驾驶舱 **0ms 立即呈现** 上次保存的本地离线快照，随后后台静默更新。 | **强烈推荐所有开发者**。消灭白屏转圈，体验最顺畅丝滑。 |
+| **⚡ 秒开模式 (SWR, 默认)** | 打开驾驶舱 **0ms 立即呈现** 上次保存的本地离线快照，并在 300ms 内后台静默更新——无论快照多旧，打开即自愈为最新。 | **强烈推荐所有开发者**。消灭白屏转圈，体验最顺畅丝滑。 |
 | **📋 仅手动刷新 (Manual Only)** | 仅浏览本地已有数据，绝对不自动发起任何后台 `gh` 网络拉取。 | **笔记本电池供电、低配设备或弱网环境**。极致节能，杜绝无谓后台开销。 |
-| **⏱️ 定时自动轮询 (Auto Poll)** | 打开驾驶舱后，按照选定的时间间隔（1m~1h）在后台自动轮询。 | **维护者工作站、实时监控大屏**。始终保持第一手待办同步。 |
 
 * **离线韧性保障 (Fail-Safe)**：即使完全断网或后台请求超时，**界面依然完整保留本地快照供您浏览与检索，绝不发生白屏或红字崩溃报错！**
 
@@ -245,10 +344,12 @@ pnpm dsh plugin add dsh-github-flow
         defaultTimeoutMs: 30000   # 命令执行超时时间（毫秒，默认 30 秒）
         maxOutputChars: 24000     # 单次命令安全返回字符数上限（Token 防溢出保护）
         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'；仅未在驾驶舱设置过时生效，界面设置优先）
 ```
 
 ---
@@ -277,6 +378,12 @@ export function apply(ctx: Context) {
 - [npm 发布与自动化 CI 发版指南](./docs/npm-publish-guide.md)
 - [架构设计与技术规范](./docs/architecture.md)
 
+
+---
+## 友情链接
+
+- [LINUX DO - 新的理想型社区](https://linux.do/)
+
 ---
 
 ## 📄 开源协议 (License)

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,22 +21,33 @@
 │     │   - 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 超时)   │        │
 │     └──────┬───────────────────────┬────────────────────────┬──────┘        │
 │            │                       │                        │               │
 │            ▼                       ▼                        ▼               │
 │  ┌──────────────────┐    ┌──────────────────┐    ┌───────────────────────┐  │
-│  │  5 大 Agent 工具  │    │  人类 Slash 指令 │    │   Host HTTP WebServer │  │
+│  │  9 大 Agent 工具  │    │  人类 Slash 指令 │    │   Host HTTP WebServer │  │
 │  │  (defineTool DSL)│    │  /gh status      │    │ (Effect Disposer 清理)│  │
 │  │  - pr            │    │  /gh upgrade     │    │ - /api/github/overview│  │
 │  │  - issue         │    │  /gh help        │    │ - /api/github/action  │  │
 │  │  - run           │    └──────────────────┘    │ - /api/github/refresh │  │
-│  │  - repo          │                            │ - /check-update (闲时)│  │
+│  │  - repo          │                            │ - /check-update (并行)│  │
 │  │  - api (逃生门)  │                            │ - /upgrade (一键自动) │  │
-│  └──────────────────┘                            └──────────┬────────────┘  │
-│                                                             │               │
-│                                                             │ HTTP API      │
+│  │  - release       │                            │ - /update-settings    │  │
+│  │  - secret (stdin)│                            │ - /proxy (全局代理)   │  │
+│  │  - skill         │                            │ - /auth (轻量探针)    │  │
+│  │  - help (元指南) │                            └──────────┬────────────┘  │
+│  └────────┬─────────┘                                       │               │
+│           │                                                 │               │
+│           ▼                                                 │               │
+│  ┌──────────────────────────────────┐                       │               │
+│  │  Markdown 渲染引擎 (renderers/)  │                       │               │
+│  │  - 列表表格化压缩 70%+ Token     │                       │               │
+│  │  - 状态徽章/超链接/转义防破损     │                       │               │
+│  │  - 高危确认卡片/敏感字段隔离      │                       │               │
+│  └──────────────────────────────────┘                       │               │
 └─────────────────────────────────────────────────────────────┼───────────────┘
                                                               │
 ┌─────────────────────────────────────────────────────────────┼───────────────┐
@@ -50,7 +61,9 @@
 │   │   - 用户提单 / 分配待办 / 我发起 │    │  - 快捷操作网格 (直达入口)   │   │
 │   │   - 顶部升级通知横幅 (Banner)    │    │  - 紧凑微型升级指示条       │   │
 │   │   - 动态数据新鲜度胶囊与 SWR 缓存│    │  - 本地快照胶囊 (对齐规则)  │   │
-│   │   - 数据同步设置弹窗 (Modal)     │    │                             │   │
+│   │   - 四分区设置弹窗 (同步/代理/   │    │  - ⚙️ 完整设置入口 (复用    │   │
+│   │     更新源/关于)                │    │     主页同一弹窗组件)       │   │
+│   │   - 「插件」身份徽章 (关于直达)  │    │  - 「插件」身份徽章 (直达)  │   │
 │   └──────────────────────────────────┘    └─────────────────────────────┘   │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
@@ -72,8 +85,13 @@
 ### 2.3 上下文 Token 保护与防御性输出包装 (Token Budget Guard)
 - 所有的 `gh` 查询原生采用 `--json <fields>` 结构化投影；
 - 对长文本输出（如大型 PR 的完整 `diff`、CI 失败步骤日志）设置安全截断阈值（默认 24KB），采用码点安全切割与二分查找字节截断，保留头尾关键上下文并添加显式截断标记，杜绝撑爆模型上下文；
+- 列表与详情输出经独立 Markdown 渲染引擎（`src/renderers/markdown.ts`）转化为高密度表格与卡片（带状态徽章、可点击超链接与竖线转义防护），实测 20 条 PR 列表输出压缩 70%+ Token；
 - 所有 Agent 工具的输出统一经过归一化，列表自动打包为 `{ items, count }`，标量打包为 `{ result }`，100% 严丝合缝契合 DSH 工具网关模式约束。
 
+### 2.3.1 高危操作确认与敏感值安全通道 (Safety Confirmation & Secret stdin Channel)
+- 不可逆写操作（`merge` / `close` / `release delete` / clobber 覆盖上传 / `secret delete` / `skill install`）强制要求 `confirm: true` 显式参数，未确认时仅返回影响评估卡片，不产生任何远端或本地副作用；
+- 密钥明文仅经子进程标准输入传递（`spawnWithStdin` 通道：`spawn` + `stdin.end(data)` 半关闭写入——`execFile` 的 `input` 选项在实测环境从不真正写入管道，密文通道此前从未生效过），全程不出现在命令行参数、进程列表与工具输出中；渲染层对 secret 输出采用独立实现，从结构上隔离「绝不渲染 value 字段」这条安全红线。
+
 ### 2.4 原生浅色/深色主题自适应与快捷操作网格
 - 全面对齐 DSH 官方 DSW 语义设计变量，基于 `body[data-ds-dark-theme]` 驱动无闪烁双模式切换；
 - 右侧栏快捷操作栏彻底废弃失效的阻塞弹窗，全面采用官方直达模式（查看所有 Issues、查看 PRs、Compare / New Issue），享有 100% 官方富文本体验。
@@ -99,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`）；
@@ -123,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
 ```
 
@@ -98,3 +105,19 @@ npm publish --access public
 ### Q2: 报错 `403 You cannot publish over the previously published versions`
 - **原因**：当前打 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 天）；
+  2. 当用户执行未指定版本号的裸名安装命令（如 `dsh plugin add dsh-github-flow`）时，pnpm 的 `filterPkgMetadataByPublishDate` 过滤器会自动剔除发布未满 24 小时的新版本，并将解析上下文中的 `dist-tags.latest` 动态降级回退到**满足安全年龄的上一版本**；
+  3. 用户终端安装输出中的第一行 `✓ Lockfile passes supply-chain policies (...)` 即为该供应链策略生效的标志。
+- **解法**：
+  1. **立即尝鲜安装最新版**：在命令末尾**显式指定目标版本号**（pnpm 会判定为开发者显式信任指定版本，将其加入 `minimumReleaseAgeExclude` 白名单并成功安装）：
+     ```powershell
+     dsh plugin --profile desktop add dsh-github-flow@<最新版本号>
+     ```
+  2. **自然解禁**：新版本在 npm 上的发布时间达到 24 小时后，安全锁定期自动解除，届时所有用户直接运行裸名安装命令均会默认解析安装最新版。