dsh-github-flow 0.1.7 → 0.2.0

package/README.md

@@ -5,11 +5,12 @@
   <a href="https://www.npmjs.com/package/dsh-github-flow"><img src="https://img.shields.io/npm/dm/dsh-github-flow.svg?style=flat-square&color=2ea043" alt="npm downloads" /></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license" /></a>
   <a href="https://deepseek-harness.github.io/deepseek-harness/"><img src="https://img.shields.io/badge/Cordis-Compatible-8957e5.svg?style=flat-square" alt="Cordis" /></a>
+  <img src="https://img.shields.io/badge/Platform-macOS%20%7C%20Windows%20%7C%20Linux-informational.svg?style=flat-square" alt="Platform" />
 </p>
 
 <p align="center">
-  <b>基于 GitHub CLI (<code>gh</code>) 为 DeepSeek Harness (DSH) 打造的现代化原生工作流集成插件。</b><br>
-  深度打通本地 Git 仓库开发与远程 GitHub 协作（PR、Issue、Actions CI 诊断与代码审查），兼备 Agent 模型工具、人类 Slash 指令以及原生 Web UI 双重视图。
+  <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>。
 </p>
 
 <p align="center">
@@ -18,133 +19,354 @@
 
 ---
 
-## 🌟 核心特性
+## 🎯 为什么需要 `dsh-github-flow`？
 
-1. **零鉴权配置，开箱即用**：
-   - 自动复用宿主机已通过 `gh auth login` 认证的登录凭据（OAuth Token / 系统 Keyring），无需在 DSH 中存储任何明文 GitHub PAT。
-2. **工作区目录深度亲和与零参数探测 (CWD & Git Auto-Binding)**：
-   - 自动绑定当前会话所在的物理工作区目录，原生直读本地 `.git/config` 并映射 `workspace.json`；具备 Git 强校验、父子级目录智能穿透与会话 ID 上下文透传机制，杜绝非 Git 目录误选，无需 Agent 或人类手动传参 `owner/repo`，零参数直接识别关联仓库。
-3. **高信噪比与 Token 防溢出治理**：
-   - 拒绝 70+ 个碎片化微型工具撑爆上下文，收敛聚合为 **5 大领域核心 Tool**。
-   - 所有查询原生采用 `--json <fields>` 按需返回；对 `diff`、`log_failed` 设置安全截断保护（默认 24KB），防止模型上下文窗口溢出崩溃。
-   - 工具层已通过防御性输出包装，列表与标量 100% 契合 DSH 工具网关模式约束。
-4. **原生 Web UI 双重视图与多维任务治理**：
-   - **全局驾驶舱**（主导航栏 `sidebar.panellist`，Order 20）：透视账号全局仓库、本地工作区矩阵联动状态；重构并支持**三维 Issue 智能聚合**（「📥 用户提单」/「🎯 分配待办」/「✍️ 我发起的」），提供四态响应式药丸过滤与身份徽章；
-   - **右侧栏工作区面板**（`sidebarRightTabs`，Order 40）：自动绑定当前工程，常驻呈现 PR 门禁状态、**当前仓库 Open Issues 任务列表**（带提出人、分类徽章、标签与直达链接）、CI 构建流水线，以及快捷黄金网格（浏览器打开、查看所有 Issues、查看所有 PRs、快速创建 PR、新建 Issue），零弹窗依赖；
-   - **全场景双模式原生自适应**：深度契合 DSH 官方 DSW（DeepSeek Web）设计变量规范，通过 `body[data-ds-dark-theme]` 驱动浅色与深色主题实时零延迟平滑切换。
-5. **健全的环境诊断与三态就绪引导 (Three-State Setup Engine)**：
-   - 告别空状态困惑：精准建立「未安装 CLI (`Missing`)」➜「已安装未登录 (`Required`)」➜「已认证就绪 (`Active`)」三态状态机；
-   - 自动识别宿主机操作系统（Windows/macOS/Linux），按平台提供包管理器安装命令（Windows 下 `winget install --id GitHub.cli`、macOS 下 `brew install gh`）与官方安装包直达；
-   - 支持一键复制命令与安全白名单系统终端一键唤起；
-   - 具备**窗口焦点自愈（Focus Auto-Recovery）**机制：切到外部终端或浏览器授权完毕后，切回 DSH 界面自动探测刷新，无感恢复。
-6. **符合 Cordis 官方微内核架构**：
-   - 暴露原生 `GitHubService`（`ctx.github`），允许生态其他插件复用；
-   - 具备符合 Standard Schema 规范的运行时配置校验（`Config`）；
-   - 支持领域事件系统（`github/pr:create`, `github/issue:create`）。
+在日常使用 AI Agent 辅助编程与工程研发时，开发者经常遭遇以下断层痛点：
+
+| 研发协作场景 | 传统方式（痛点重重） | `dsh-github-flow`（原生体验） |
+| :--- | :--- | :--- |
+| **Agent 提 PR & 代码评审** | 用户必须手动在网页复制分支、点开 GitHub 网页点鼠标提交 PR，无法实现自主研发闭环。 | **Agent 原生提单与评审**：对 Agent 说“帮我把当前分支提个 PR”，Agent 调用 `github_pr` 自动完成提交与代码 diff 审查。 |
+| **CI / Actions 构建报错修复** | 构建挂了后，开发者在网页翻几十页 Actions 日志，复制报错贴给 Agent 调试。 | **精准抓取报错**：对 Agent 说“看下 CI 为什么失败”，Agent 调 `github_run(log_failed)` 秒级定位失败步骤并自动修复代码。 |
+| **安全性与鉴权维护** | 必须在插件配置文件里贴明文 GitHub Token（PAT），面临权限失控与密钥泄漏风险。 | **0 密钥泄露风险**：直接复用机器本地已认证的 `gh auth login` 凭据，使用系统安全 Keyring。 |
+| **多任务切屏困扰** | 必须在 VS Code、浏览器 GitHub 标签页和 DSH 聊天窗之间反复切屏，上下文频繁丢失。 | **内置沉浸式全景工作台**：DSH 内部常驻 PR 门禁、CI 流水线、三维待办 Issue 矩阵，一目了然。 |
+| **首屏加载与性能等待** | 每次打开全景驾驶舱全屏白屏卡死转圈 8~15 秒，等待所有网络与子进程请求返回。 | **SWR 0ms 瞬间秒开**：打开立即呈现本地持久化快照，后台静默重验；提供专属设置面板自主调节拉取间隔与纯手动模式。 |
+| **插件维护与升级** | 插件更新全靠开发者去 npm 碰运气看版本号，命令复杂不敢升。 | **闲时静默探测 + Web 一键自动升级**：双源极速探测，自动适配 Mac/Windows 跨平台命令，界面点击即升。 |
+
+---
+
+## 🚀 安装指南
+
+### 步骤 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 工程环境
+pnpm dsh plugin 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 的手和脚
+
+本插件精选聚合为 **9 大领域核心工具**，拒绝几十个无用微型工具撑爆 Agent 上下文，原生搭载 **Token 防溢出保护（默认 24KB 智能二分截断）**、**高密度 Markdown 原生渲染（列表输出压缩 70%+ Token）** 与 **零参数 CWD 智能绑定**。
+
+### 1. `github_pr`：PR 全生命周期管理与自动化代码审查
+> **典型对话指令**：
+> - *"帮我检查当前仓库有没有需要我审查的 PR？"*
+> - *"帮我把当前特性分支创建一个 PR，标题叫 'feat: add dark mode'，附带简明改动说明"*
+> - *"审查 PR #12 的代码差异并给出安全重构建议"*
+> - *"检查 PR #8 的 CI 检查通过了吗？通过的话帮我 Squash 合并并删除源分支"*
+
+* **支持操作 (`action`)**：
+  * `list`：列出当前仓库开放的 PR（带作者、审查判定、CI 门禁状态，支持 `state` / `author` / `limit` 过滤）；
+  * `view`：查看指定 PR 详情、描述与元数据；
+  * `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`；需 `confirm: true` 二次确认）。
+
+---
+
+### 2. `github_run`：CI 流水线排查与失败定位神器（Agent 自动修 Bug 核心）
+> **典型对话指令**：
+> - *"最近一次 Actions 工作流为什么挂了？提取失败步骤日志并帮我修复"*
+> - *"看一下当前仓库最近 5 次 CI 构建的状态"*
+> - *"重新运行刚才失败的工作流"*
+
+* **支持操作 (`action`)**：
+  * `log_failed`（🔥 **核心杀手锏**）：**专供 Agent 快速诊断**，自动抓取并剥离无关日志，精准提取失败 Step 的关键错误堆栈，供 Agent 直击问题修复代码；
+  * `list`：查看当前仓库的 Workflow 运行历史与结论（支持 `branch` / `status: failure` 快速锁定失败构建）；
+  * `view`：查看指定 run_id 的详细阶段（Jobs & Steps）；
+  * `trigger`：🆕 主动触发 `workflow_dispatch` 工作流（提交修复后立即验证远端 CI）；
+  * `rerun`：重新触发失败的 CI 运行；
+  * `cancel`：取消在途的工作流。
+
+---
+
+### 3. `github_issue`：缺陷跟踪与待办任务闭环
+> **典型对话指令**：
+> - *"把刚才复现的内存泄漏 Bug 提一个 Issue，打上 'bug' 和 'backend' 标签"*
+> - *"查看指派给我的所有待办 Issue"*
+> - *"给 Issue #45 追加评论：'已经在 master 分支修复，等待发版验证'"*
+> - *"把 Issue #45 关闭"*
+
+* **支持操作 (`action`)**：
+  * `list`：多条件检索 Issue 列表（`state` / `labels` / `assignees` / `limit`）；
+  * `view`：查看 Issue 正文与评论历史；
+  * `create`：创建新 Issue（支持标题、正文、标签、指派人）；
+  * `edit`：🆕 修改标题、正文与增删标签；
+  * `develop`：🆕 从 Issue 一键切出关联开发分支并本地检出，打通「读需求 → 写代码」闭环；
+  * `comment`：在指定 Issue 中追加排查进展或评论；
+  * `close`（需 `confirm: true`）/ `reopen`：开启或关闭 Issue。
+
+---
+
+### 4. `github_repo`：仓库探索与跨代码库检索
+> **典型对话指令**：
+> - *"在当前关联的 GitHub 仓库里搜索使用到 'createPrTool' 的代码行"*
+> - *"在 GitHub 上检索关于 'dsh-plugin' 的优秀开源项目"*
+> - *"查看仓库 cli/cli 的基本信息与星标数"*
+
+* **支持操作 (`action`)**：
+  * `view`：查看当前或目标仓库的元数据（默认分支、星标、描述、Topics 与开源协议）；
+  * `sync`：🆕 一键拉平 Fork 仓库与上游主干，解决贡献开源项目时 Fork 落后导致 CI 门禁失败；
+  * `search_code`：跨仓库或当前仓库检索特定代码符号；
+  * `search_repos`：跨全站检索 GitHub 开源仓库。
 
 ---
 
-## 📸 界面预览
+### 5. `github_api`：底层的灵活“逃生门”
+> **典型对话指令**：
+> - *"调用 GitHub API 获取当前仓库最新的 Release 列表，用 jq 提取 tag 名称"*
 
-### 全局全景驾驶舱 (Global Cockpit)
-透视账号云端所有 GitHub 仓库、本地工作区矩阵联动状态，以及待办 PR 和多维分类 Issues（支持用户提单、指派待办、我发起的多维药丸切换与状态徽章）：
+* **核心优势**：直接复用本地认证环境调用任意 REST / GraphQL API，支持 `--jq` 预过滤、`raw` 原始响应模式与 `paginate` 自动翻页聚合，绝不因插件未封装特定接口而受限。
+
+---
+
+### 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)
+
+点击 DSH 左侧主导航的 GitHub 图标进入：
+* **⚡ 0ms 瞬间秒开直出 (SWR 本地持久化缓存)**：利用客户端本地持久化快照，告别每次进入转圈等待 8~15 秒的烦躁感，打开瞬间完整渲染全部卡片与列表；
+* **📦 实时数据新鲜度胶囊**：标题栏旁直观展示数据状态（`[📦 本地快照 (21分钟前)]` ➔ `[⏳ 后台同步中...]` ➔ `[✅ 已是最新 (15:30)]` ➔ `[⚠️ 同步超时已保留缓存]`）；
+* **账号全景概览**：实时透视名下所有 GitHub 仓库、默认分支与 Star 状态；
+* **本地工作区联动矩阵**：自动探测本机所有打开的项目，显示当前工作区与远程 GitHub 仓库的关联状态；
+* **三维待办 Issue 矩阵**：智能划分「📥 用户提单（反馈到我名下仓库）」、「🎯 指派待办（分配给我）」与「✍️ 我发起的」，支持一键药丸过滤；
+* **升级提示横幅**：检测到新版本时在顶部优雅滑出，提供一键自动升级与更新日志直达。
 
 <p align="center">
   <img src="./docs/images/1.png" alt="GitHub 全景驾驶舱" width="100%" />
 </p>
 
-### 会话右侧栏工作区面板 (Session Workspace Panel)
-自动绑定当前工程关联仓库，常驻呈现 PR 状态药丸、当前仓库 Open Issues 任务列表、Actions 构建流水线与快捷操作网格：
+### 2. 会话右侧栏工作区面板 (Session Workspace Panel)
+位于每个对话工作区的右侧抽屉栏：
+* **当前仓库上下文绑定**：自动锁定当前会话的 Git 仓库，无需选择；
+* **数据新鲜度胶囊对齐**：标题旁紧凑呈现 `[📦 本地快照 (2分钟前)]` 与 `[🔄 刷新]` 按钮，与主页规则 100% 保持一致，首屏 0ms 瞬间直出；
+* **PR 门禁状态药丸**：展示当前开放 PR，悬停查看 Checks 结果与审核意见；
+* **当前仓库 Open Issues 列表**：直接在侧边栏审查待办任务并提供直达链接；
+* **最新 Actions 构建流水线**：实时关注 CI 状态；
+* **快捷操作网格**：一键在浏览器打开仓库、直达 Issues/PRs、一键创建 PR。
 
 <p align="center">
   <img src="./docs/images/2.png" alt="右侧栏工作区面板" width="100%" />
 </p>
 
+### 3. 设置中心 (Settings Modal)
+点击全景驾驶舱右上角 **`[⚙️ 设置]`** 打开分区式设置弹窗，左侧分区导航、右侧内容独立滚动（窄屏自动折叠为横向页签）：
+
+**🔄 数据同步分区**——调优数据拉取节奏：
+* **两种同步策略**：
+  * **⚡ 秒开模式 (SWR, 推荐)**：打开驾驶舱立即展示上次本地缓存（0ms秒开），并在 300ms 内后台静默同步最新状态——无论缓存多旧，打开即可自愈为最新；
+  * **📋 仅在手动点击时拉取 (Manual Only)**：打开只浏览本地缓存，绝不自动触发后台 gh 进程，最省电、最省资源；想更新时点击「🔄 刷新」即可。
+* **本地缓存可视化管理**：透明查看本地快照体积与保存时间戳，支持一键 `[🗑️ 清空缓存]` 重置。
+
+**🌐 网络代理分区**——让插件全部外联流量走你的代理：
+* **全局生效范围**：设置后驾驶舱、右侧栏面板、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 回环请求永不被代理劫持。
+
+| 🔄 数据同步分区 | 🌐 网络代理分区 |
+| :---: | :---: |
+| ![设置中心·数据同步分区](./docs/images/3.png) | ![设置中心·网络代理分区](./docs/images/4.png) |
+
 ---
 
-## 🚀 安装指南
+## ⚡ 智能升级与版本检查机制
 
-在 DSH 终端执行以下命令直接从 npm 安装：
+再也不用担心错过新功能！`dsh-github-flow` 内置了工业级的版本管理机制：
 
-```bash
-# 安装到桌面端 Profile
-dsh plugin --profile desktop add dsh-github-flow
+1. **业务优先，闲时静默后置**：
+   - 打开 Web 界面时，**核心 PR / Issue 数据 100% 毫秒级优先拉取渲染**；
+   - 在所有业务数据渲染就绪后，前端延迟 1.5 秒利用空闲时间发起后台探针，**对主业务 0 阻塞、0 抢占**。
+2. **国内双源智能加速**：
+   - 默认第一顺位走 **阿里云/淘宝 npm 镜像**（国内延迟仅 50~150ms），超时自动无缝回退官方 npmjs 兜底。
+3. **跨平台一键自动升级**：
+   - **界面直升**：在全景驾驶舱或右侧栏点击 **`[⚡ 一键自动升级]`**，插件在后台安全执行拉取；
+   - **智能适配**：自动识别 macOS、Windows 与桌面版 Profile，Mac 环境下自动补全 Homebrew 环境变量；
+   - **源码保护防线**：检测到本地 Git 源码软链接模式（`link:`）时自动阻止覆盖，防止破坏开发工作区；
+   - **成功自愈提示**：升级成功后明确提醒重启 DSH 服务以激活后端新工具，也可点击按钮立即刷新页面预览新界面。
+
+---
+
+## ⏱️ SWR 秒开缓存与数据拉取节奏控制
 
-# 或者安装到 Web Profile
-dsh plugin --profile web add dsh-github-flow
+为什么以前打开全景驾驶舱需要等待好几秒？因为全景数据要并发调用十余次 `gh` 进程扫描多个仓库与工作区。本插件引入了 **Stale-While-Revalidate (SWR)** 缓存体系，并把控制权完全交还给用户：
+
+```
+首次渲染 (0ms) ──────────> 恢复本地持久化快照，瞬间完整上屏
+                                │
+                                ├── SWR 模式: 延迟 300ms 后台静默拉取，平滑对齐最新数据
+                                └── 手动模式: 仅浏览本地快照，点击「🔄 刷新」才发起拉取
 ```
 
----
+### 两种刷新策略对比与选用建议：
 
-## 🛠️ Agent 工具集速查
+| 刷新模式 | 运行机制 | 适用人群与场景 |
+| :--- | :--- | :--- |
+| **⚡ 秒开模式 (SWR, 默认)** | 打开驾驶舱 **0ms 立即呈现** 上次保存的本地离线快照，并在 300ms 内后台静默更新——无论快照多旧，打开即自愈为最新。 | **强烈推荐所有开发者**。消灭白屏转圈，体验最顺畅丝滑。 |
+| **📋 仅手动刷新 (Manual Only)** | 仅浏览本地已有数据，绝对不自动发起任何后台 `gh` 网络拉取。 | **笔记本电池供电、低配设备或弱网环境**。极致节能，杜绝无谓后台开销。 |
 
-| 工具名称 | 核心操作 (`action`) | 典型场景 |
-|---|---|---|
-| `github_pr` | `list`, `view`, `create`, `diff`, `checks`, `review`, `merge` | 让 Agent 查看 PR 详情、检查 CI 状态、执行代码评审、合并 PR |
-| `github_issue` | `list`, `view`, `create`, `comment`, `close`, `reopen` | 查看与搜索 Issue、创建 Issue、追加排查进展评论 |
-| `github_run` | `list`, `view`, `log_failed`, `rerun`, `cancel` | 查看 CI 构建流水线，特别是 `log_failed` 可直接提取报错日志供 Agent 修复 |
-| `github_repo` | `view`, `search_code`, `search_repos` | 查看仓库元数据、跨仓库代码搜索 |
-| `github_api` | 任意端点（如 `repos/{owner}/{repo}/releases`） | 底层直接调用 REST / GraphQL API（支持 `--jq` 预过滤、`raw` 原始响应体模式） |
+* **离线韧性保障 (Fail-Safe)**：即使完全断网或后台请求超时，**界面依然完整保留本地快照供您浏览与检索，绝不发生白屏或红字崩溃报错！**
 
 ---
 
-## 💬 人类 Slash 命令
+## 💬 人类 Slash 指令速查
 
-在 DSH 对话输入框直接使用：
-- `/gh status`：检查当前 GitHub CLI 账号登录状态、授权作用域与当前本地目录关联仓库；
-- `/gh help`：查看使用帮助与常见语法示例。
+在 DSH 任意聊天窗口输入：
+
+* `/gh status`：一键诊断当前 GitHub CLI 账号认证状态、作用域、当前工作区关联仓库及插件版本；
+* `/gh upgrade`：主动检测 npm 最新版本，自适应输出当前操作系统（macOS / Windows / Linux）的最佳升级指引；
+* `/gh help`：查看帮助说明与 Agent 典型对话范例。
 
 ---
 
-## ⚙️ 插件配置项 (Config)
+## ⚙️ 配置项说明 (`cordis.patch.yml`)
 
-在 `cordis.patch.yml` 或 Profile 配置中自由覆盖如下字段：
+插件具备开箱即用的默认行为，也可在 `cordis.patch.yml` 或 Profile 中按需调优：
 
 ```yaml
 - insert:
     - id: github-flow
       name: dsh-github-flow
       config:
-        ghPath: 'gh'              # GitHub CLI 程序路径（内网或特定环境可指定绝对路径）
-        defaultTimeoutMs: 30000   # 命令执行超时时间（毫秒）
-        maxOutputChars: 24000     # 单次命令最大返回字符数（防 Token 溢出保护）
-        maxOutputBytes: 96000     # 单次命令最大返回字节数硬上限，默认 maxOutputChars × 4
-        cacheTtlMs: 15000         # 单仓库概览缓存时长（毫秒）；全局驾驶舱按此值的 20 倍缓存，下限 5 分钟
-        defaultListLimit: 20      # 默认查询列表返回条数
+        ghPath: 'gh'              # GitHub CLI 可执行程序路径（内网特定环境可指定绝对路径）
+        defaultTimeoutMs: 30000   # 命令执行超时时间（毫秒，默认 30 秒）
+        maxOutputChars: 24000     # 单次命令安全返回字符数上限（Token 防溢出保护）
+        maxOutputBytes: 96000     # 单次命令 UTF-8 字节数硬上限，默认 maxOutputChars × 4
+        defaultListLimit: 20      # 列表类查询默认返回条数（pr/issue/run/release/skill 通用）
+        cacheTtlMs: 15000         # 单仓库概览缓存时长（毫秒，默认 15 秒）
+        checkUpdate: true         # 是否开启新版本自动检查提示（默认开启）
+        updateCheckIntervalMs: 86400000 # 检查更新间隔（毫秒，默认 24 小时）
+        registryUrl: ''           # 自定义私有 npm 镜像地址（留空则自动选用 npmmirror 与 npmjs）
+        proxyUrl: ''              # 代理地址预置默认值（如 'http://127.0.0.1:7890'；仅未在驾驶舱设置过时生效，界面设置优先）
 ```
 
-> 关于 Web 面板的刷新节奏：全局驾驶舱每次刷新要执行十余次 `gh`（本机实测 8-13 秒），
-> 因此它按 5 分钟缓存，并在你点击「🔄 刷新全局数据」时强制重取。
-> 工作区矩阵只读取本地 `.git/config` 识别仓库归属，不发起网络请求。
-> `/gh status` 命令始终绕过认证缓存，保证你 `gh auth login` 后立刻能看到真实状态。
-
 ---
 
 ## 🔌 生态服务扩展 (Cordis Service)
 
-其他 DSH 插件可通过依赖注入复用本插件的能力：
+本插件提供标准 Cordis 原生服务 `ctx.github`。其他 DSH 插件只需声明依赖即可复用：
 
-```ts
+```typescript
 import type { Context } from '@deepseek-ai/cordis';
 
 export const inject = ['github'];
 
 export function apply(ctx: Context) {
-  // 通过 ctx.github 直接调用底层安全执行引擎
+  // 直接调用经过安全包装的底层执行引擎
   const auth = await ctx.github.checkAuth();
   const repo = await ctx.github.getRepoMetadata();
+  const prs = await ctx.github.run(['pr', 'list', '--json', 'number,title']);
 }
 ```
 
 ---
 
-## 📚 开发与维护文档
+## 📚 相关开发文档
 
-- [npm 发布与版本维护指南](./docs/npm-publish-guide.md)
+- [npm 发布与自动化 CI 发版指南](./docs/npm-publish-guide.md)
 - [架构设计与技术规范](./docs/architecture.md)
 
+
+---
+## 友情链接
+
+- [LINUX DO - 新的理想型社区](https://linux.do/)
+
 ---
 
 ## 📄 开源协议 (License)
 
-本项目基于 [MIT License](./LICENSE) 协议开源。
+本项目基于 [MIT License](./LICENSE) 协议完全开源。欢迎提交 PR 与 Issue！

package/docs/architecture.md

@@ -12,7 +12,7 @@
 │                                                                             │
 │  ┌────────────────────────┐                   ┌──────────────────────────┐  │
 │  │   Cordis Context (ctx) │                   │      PluginConfig        │  │
-│  │                        │                   │(Schemastery 运行时校验)   │  │
+│  │   - inject: tools, cmd │                   │(Schemastery 运行时校验)   │  │
 │  └───────────┬────────────┘                   └─────────────┬────────────┘  │
 │              │                                              │               │
 │              ▼                                              ▼               │
@@ -20,18 +20,33 @@
 │     │               GitHubService (ctx.github 原生服务)             │        │
 │     │   - checkAuth(cwd)      - getRepoMetadata(cwd)               │        │
 │     │   - run<T>(args, opts)  [execFile 数组隔离 + 24KB 智能截断]     │        │
+│     │                                                              │        │
+│     │   - UpdateChecker (双源极速探测 + 24h 缓存 + Fail-Safe)        │        │
+│     │   - UpgradeManager (跨平台自适应 + 互斥锁 + macOS PATH 补全)   │        │
 │     └──────┬───────────────────────┬────────────────────────┬──────┘        │
 │            │                       │                        │               │
 │            ▼                       ▼                        ▼               │
 │  ┌──────────────────┐    ┌──────────────────┐    ┌───────────────────────┐  │
-│  │  5 大 Agent 工具  │    │  人类 Slash 指令 │    │   Host HTTP WebServer │  │
-│  │  (defineTool DSL)│    │  /gh status|help │    │ (Effect Disposer 清理)│  │
-│  │  - pr            │    └──────────────────┘    │ - /api/github/overview│  │
-│  │  - issue         │                            │ - /api/github/action  │  │
-│  │  - run           │                            │ - /api/github/refresh │  │
-│  │  - repo          │                            └──────────┬────────────┘  │
-│  │  - api (逃生门)  │                                       │               │
-│  └──────────────────┘                                       │ HTTP API      │
+│  │  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 (闲时)│  │
+│  │  - api (逃生门)  │                            │ - /upgrade (一键自动) │  │
+│  │  - release       │                            └──────────┬────────────┘  │
+│  │  - secret (stdin)│                                       │               │
+│  │  - skill         │                                       │ HTTP API      │
+│  │  - help (元指南) │                                       │               │
+│  └────────┬─────────┘                                       │               │
+│           │                                                 │               │
+│           ▼                                                 │               │
+│  ┌──────────────────────────────────┐                       │               │
+│  │  Markdown 渲染引擎 (renderers/)  │                       │               │
+│  │  - 列表表格化压缩 70%+ Token     │                       │               │
+│  │  - 状态徽章/超链接/转义防破损     │                       │               │
+│  │  - 高危确认卡片/敏感字段隔离      │                       │               │
+│  └──────────────────────────────────┘                       │               │
 └─────────────────────────────────────────────────────────────┼───────────────┘
                                                               │
 ┌─────────────────────────────────────────────────────────────┼───────────────┐
@@ -43,6 +58,9 @@
 │   │   - 本地工作区矩阵透视           │    │  - PR 列表与 CI Checks 药丸 │   │
 │   │   - 三维待办 Issues (药丸筛选)   │    │  - 仓库 Open Issues 任务列表│   │
 │   │   - 用户提单 / 分配待办 / 我发起 │    │  - 快捷操作网格 (直达入口)   │   │
+│   │   - 顶部升级通知横幅 (Banner)    │    │  - 紧凑微型升级指示条       │   │
+│   │   - 动态数据新鲜度胶囊与 SWR 缓存│    │  - 本地快照胶囊 (对齐规则)  │   │
+│   │   - 数据同步设置弹窗 (Modal)     │    │                             │   │
 │   └──────────────────────────────────┘    └─────────────────────────────┘   │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
@@ -63,22 +81,28 @@
 
 ### 2.3 上下文 Token 保护与防御性输出包装 (Token Budget Guard)
 - 所有的 `gh` 查询原生采用 `--json <fields>` 结构化投影；
-- 对长文本输出（如大型 PR 的完整 `diff`、CI 失败步骤日志）设置安全截断阈值（默认 24KB），保留头尾关键上下文并添加显式截断标记，杜绝撑爆模型上下文；
-- 所有 Agent 工具的输出统一经过 `normalizeOutput` 归一化，列表自动打包为 `{ items, count }`，标量打包为 `{ result }`，100% 严丝合缝契合 DSH 工具网关模式约束。
+- 对长文本输出（如大型 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` 显式参数，未确认时仅返回影响评估卡片，不产生任何远端或本地副作用；
+- 密钥明文仅经子进程标准输入传递（`execFile` 的 `input` 选项），全程不出现在命令行参数、进程列表与工具输出中；渲染层对 secret 输出采用独立实现，从结构上隔离「绝不渲染 value 字段」这条安全红线。
 
 ### 2.4 原生浅色/深色主题自适应与快捷操作网格
 - 全面对齐 DSH 官方 DSW 语义设计变量，基于 `body[data-ds-dark-theme]` 驱动无闪烁双模式切换；
-- 右侧栏快捷操作栏彻底废弃失效的 Electron `prompt()` 阻塞弹窗，全面采用官方直达模式（查看所有 Issues、查看 PRs、Compare / New Issue），享有 100% 官方富文本体验。
+- 右侧栏快捷操作栏彻底废弃失效的阻塞弹窗，全面采用官方直达模式（查看所有 Issues、查看 PRs、Compare / New Issue），享有 100% 官方富文本体验。
 
 ### 2.5 Cordis 微内核标准规范
-- **服务依赖就绪**：声明 `['tools', 'commands', 'webServer', 'workspaceRegistry']`，确保 Web 路由与命令服务在环境就绪后激活；
+- **按需依赖声明**：显式声明核心必需服务 `['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` 提供 `open_terminal` 安全白名单唤起接口（只允许预设命令），避免在前端模拟复杂交互式 PTY 的脆弱性；
+- **安全辅助与白名单终端唤起**：Web 端提供一键命令复制，后端 `/api/github/action` 提供安全白名单唤起接口，避免在前端模拟复杂交互式 PTY 的脆弱性；
 - **焦点感知自愈 (Focus Auto-Recovery)**：前端挂载 `window.focus` 事件监听，用户在外部浏览器或终端完成认证后切回 DSH 界面，自动静默重新探测并无缝更新 UI，实现零摩擦闭环体验。
 
 ### 2.7 多维 Issue 身份判定与并发聚合引擎 (Multi-Dimensional Issue Engine)
@@ -88,3 +112,36 @@
   - `created`（我发起的）：`author === currentUser`（本人亲自创建的 Issue）。
 - **三路并发搜索与 URL 去重**：后端在 `/api/github/global-overview` 中通过 `Promise.all` 同时发起 `--owner=@me`、`--assignee=@me`、`--author=@me` 检索，按 URL 唯一性合并去重并按最后更新时间统一降序排列；
 - **双端视图无缝打标**：驾驶舱提供四态响应式药丸筛选（全部/用户提单/指派待办/我发起的），右侧栏直接常驻展现当前工作区所属 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 吸收。
+- **跨平台 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)`、`⏱️ 定时自动轮询 (Auto Poll)`；
+  - **自定义后台轮询周期**：提供 1m / 5m / 15m / 30m / 1h 多档位配置；
+  - **快照容量透明与一键重置**：展示本地快照体积与保存时间戳，支持一键清空重置。
+- **离线极端容灾保护 (Fail-Safe Offline Guard)**：
+  - 后台静默重验若遭遇断网、弱网或进程超时，界面平滑降级，**100% 保持旧数据完整可用**，绝不回退至空白占位或报错中断。
+

package/docs/npm-publish-guide.md

@@ -98,3 +98,15 @@ npm publish --access public
 ### Q2: 报错 `403 You cannot publish over the previously published versions`
 - **原因**：当前打 tag 的代码版本在 `package.json` 中的 `version` 已经被发布过了。
 - **解法**：本地执行 `npm version patch` 递增版本号后再重新打 tag 推送。
+
+### 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@0.1.8
+     ```
+  2. **自然解禁**：新版本在 npm 上的发布时间达到 24 小时后，安全锁定期自动解除，届时所有用户直接运行裸名安装命令均会默认解析安装最新版。