dsh-github-flow 0.1.8 → 0.2.0

package/README.en.md

@@ -10,7 +10,7 @@
 
 <p align="center">
   <b>Give DeepSeek Harness Agents native hands and feet to operate GitHub, crafting an immersive collaboration cockpit for developers.</b><br>
-  Natively reuses host <code>gh</code> CLI login credentials to eliminate Personal Access Token (PAT) leaks; deeply bridges local Git workspaces with remote GitHub collaboration, equipped with <b>5 core domain Agent tools</b>, <b>human slash commands</b>, <b>Web UI visual cockpits</b>, and <b>cross-platform one-click seamless upgrades</b>.
+  Natively reuses host <code>gh</code> CLI login credentials to eliminate Personal Access Token (PAT) leaks; deeply bridges local Git workspaces with remote GitHub collaboration, equipped with <b>9 core domain Agent tools</b>, <b>human slash commands</b>, <b>Web UI visual cockpits</b>, and <b>cross-platform one-click seamless upgrades</b>.
 </p>
 
 <p align="center">
@@ -29,14 +29,50 @@ When using AI Agents for collaborative coding, developers frequently hit these f
 | **CI / Actions Failure Debugging** | Sifting through pages of Actions logs in a browser, copying stack traces to chat for debugging. | **Pinpoint Error Extraction**: Tell the Agent *"Why did CI fail?"*; Agent calls `github_run(log_failed)` to grab failed step logs and patch code instantly. |
 | **Security & Token Management** | Pasting plain-text Personal Access Tokens (PATs) in plugin configs, risking token leaks and permission sprawl. | **Zero Token Exposure**: Directly reuses local `gh auth login` credentials via native OS Keychains/Keyrings securely. |
 | **Context Switching Overhead** | Jumping back and forth between VS Code, browser GitHub tabs, and DSH chat windows. | **Immersive Dual Cockpit**: Live PR status, Actions pipelines, and 3D issue matrices right inside DSH. |
-| **First-Screen Latency & Loading** | Staring at full-screen spinners for 8~15s while waiting for heavy background `gh` processes. | **SWR 0ms Instant Render**: Instantly displays local persistent snapshots; dedicated settings modal to customize sync intervals and manual mode. |
+| **First-Screen Latency & Loading** | Staring at full-screen spinners for 8~15s while waiting for heavy background `gh` processes. | **SWR 0ms Instant Render**: Instantly displays local persistent snapshots; dedicated settings modal to switch between SWR auto-sync and manual mode. |
 | **Plugin Upgrades & Maintenance** | Manually checking npm registry versions, complicated commands, fear of breaking configs. | **Idle Silent Detection + One-Click Upgrade**: Dual-registry acceleration, auto macOS/Windows adaptation, upgrade with one click. |
 
 ---
 
+## 🚀 Installation Guide
+
+### Step 1: Prerequisites
+Ensure GitHub CLI (`gh`) is installed and authenticated:
+```bash
+# Windows
+winget install --id GitHub.cli
+
+# macOS
+brew install gh
+
+# Login (one-time setup)
+gh auth login
+```
+
+### Step 2: Install into DSH
+
+Run in your DSH environment:
+
+```bash
+# 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
+```
+
+> 💡 **Notice (24-Hour Supply-Chain Security Lock Window)**:  
+> DSH's bundled package manager enforces a supply-chain safety policy (`minimum-release-age = 24h`) by default to mitigate malicious package takeovers. Within **24 hours** of a new version release, running bare-name install commands without a version suffix will automatically fall back to the preceding stable version that has matured past 24 hours. To **install a newly released version immediately**, append the explicit version tag:
+> ```bash
+> dsh plugin --profile desktop add dsh-github-flow@<latest-version>
+> ```
+> Once 24 hours have passed since release, the standard bare-name command will resolve to the latest version automatically.
+
+---
+
 ## 🤖 Core Agent Tools: Equipping Agents with Native GitHub Powers
 
-Consolidates scattered GitHub endpoints into **5 core domain tools**, featuring **Token Budget Protection (default 24KB intelligent truncation)** and **Zero-argument CWD auto-binding**.
+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**.
 
 ### 1. `github_pr`: Pull Request Lifecycle & Automated Code Review
 > **Example Agent Prompts**:
@@ -46,13 +82,15 @@ Consolidates scattered GitHub endpoints into **5 core domain tools**, featuring
 > - *"Did CI checks pass for PR #8? If so, squash merge it and delete the source branch."*
 
 * **Supported Actions**:
-  * `list`: List open PRs with author, review decisions, and CI status;
+  * `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 (safely truncated against token limits);
+  * `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;
   * `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`).
+  * `merge`: Merge pull requests (`squash` / `merge` / `rebase`, optional `delete_branch`; requires `confirm: true`).
 
 ---
 
@@ -64,8 +102,9 @@ Consolidates scattered GitHub endpoints into **5 core domain tools**, featuring
 
 * **Supported Actions**:
   * `log_failed` (🔥 **Killer Feature**): **Optimized for Agents**; automatically extracts isolated error logs from failed steps for instant root-cause analysis;
-  * `list`: View recent workflow runs and conclusions;
+  * `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;
   * `rerun`: Re-trigger failed CI runs;
   * `cancel`: Cancel in-progress workflows.
 
@@ -79,11 +118,13 @@ Consolidates scattered GitHub endpoints into **5 core domain tools**, featuring
 > - *"Close Issue #45."*
 
 * **Supported Actions**:
-  * `list`: Query issues with flexible filters;
+  * `list`: Query issues with flexible filters (`state` / `labels` / `assignees` / `limit`);
   * `view`: Read issue body and discussion history;
   * `create`: Create new issues (title, body, labels, assignees);
+  * `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` / `reopen`: Manage issue lifecycle states.
+  * `close` (requires `confirm: true`) / `reopen`: Manage issue lifecycle states.
 
 ---
 
@@ -94,7 +135,8 @@ Consolidates scattered GitHub endpoints into **5 core domain tools**, featuring
 > - *"Show repository metadata and star count for cli/cli."*
 
 * **Supported Actions**:
-  * `view`: View repository metadata (default branch, stars, description, visibility);
+  * `view`: View repository metadata (default branch, stars, description, topics & license);
+  * `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.
 
@@ -104,11 +146,72 @@ Consolidates scattered GitHub endpoints into **5 core domain tools**, featuring
 > **Example Agent Prompts**:
 > - *"Call GitHub API to fetch latest releases of current repository and parse tag names with jq."*
 
-* **Core Strength**: Call any GitHub REST or GraphQL API using local credentials with `--jq` filtering and `raw` text mode.
+* **Core Strength**: Call any GitHub REST or GraphQL API using local credentials with `--jq` filtering, `raw` text mode, and `paginate` auto-aggregation.
+
+---
+
+### 6. `github_release`: Version Releases & Build Asset Delivery 🆕
+> **Example Agent Prompts**:
+> - *"Publish v0.2.0 for this repository with auto-generated release notes."*
+> - *"Upload dsh-github-flow-0.2.0.tgz to the v0.2.0 release."*
+
+* **Supported Actions**:
+  * `list` / `view`: Browse release history and per-version details (assets, notes);
+  * `create`: Create releases (`generate_notes` auto-notes, `draft` / `prerelease` flags, attach assets directly);
+  * `upload` / `download`: Upload `.tgz` build artifacts or download assets by glob pattern;
+  * `delete` (requires `confirm: true`): Delete a release, optionally cleaning up its tag.
 
 ---
 
-## 🖥️ Native Web UI Workspace & Sync Preferences
+### 7. `github_secret`: CI/CD Secrets Management 🆕
+> **Example Agent Prompts**:
+> - *"Update the NPM_TOKEN secret for this repository."*
+> - *"Show which secrets are configured for this repo."*
+
+* **Supported Actions**:
+  * `list`: Show secret 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.
+  * Supports repository / organization (`org`) / environment (`env`) scopes across `actions` / `codespaces` / `dependabot` / `agents` apps.
+
+---
+
+### 8. `github_skill`: Cross-Agent Open-Source Skills Discovery 🆕
+> **Example Agent Prompts**:
+> - *"Search GitHub for an Agent Skill about code review."*
+> - *"Preview that skill's content, then install it to this project if it looks good."*
+
+* **Supported Actions**:
+  * `search`: Search open-source `SKILL.md` skills across GitHub (Code Search based, ranked by stars);
+  * `preview`: Read-only preview of skill content before installing — nothing touches disk;
+  * `install` (requires `confirm: true`): Install to local agent hosts (Claude Code / Cursor / Copilot and 50+ others), `project` or `user` scope;
+  * `list`: List all skills installed on this machine.
+  * Requires the official `gh skill` preview feature in GitHub CLI 2.9x+.
+
+---
+
+### 9. `github_help`: Meta Guide & Troubleshooting Hub 🆕
+> **Example Agent Prompts**:
+> - *"I'm not sure which GitHub tool to use for this task."*
+> - *"How do I write advanced GitHub search syntax?"*
+
+* **Core Capabilities**:
+  * Task-routing navigation across all 9 tools;
+  * Official advanced search syntax cheat sheet (date ranges, status qualifiers, code search scopes);
+  * Self-healing recipes for common errors (403 rate limits, 422 missing params, stale forks, outdated CLI);
+  * Direct passthrough to the official `gh help <command>` offline manual.
+
+---
+
+## 🛡️ Safety Guardrails
+
+* **Destructive-action double confirmation**: `merge`, `close`, `release delete`, clobber uploads, `secret delete`, and `skill install` require an explicit `confirm: true` parameter; without it, only an impact assessment is returned — nothing executes. This prevents accidental merges or deletions from model hallucinations.
+* **Secret stdin channel**: Secret values travel via subprocess stdin — never on the command line (ps / task-manager safe), never persisted, never echoed; gh encrypts locally with the repository public key before uploading.
+* **Command-injection immunity**: All gh invocations use `execFile` array-argument isolation with zero shell string concatenation.
+
+---
+
+## 🖥️ Native Web UI Workspace & Settings Center
 
 No more window switching! Seamlessly integrated into DSH with DSW design tokens and instant light/dark theme adaptation.
 
@@ -138,47 +241,26 @@ Located in the right drawer of every chat workspace:
   <img src="./docs/images/2.png" alt="Session Right Sidebar Panel" width="100%" />
 </p>
 
-### 3. Data Sync & Cache Settings (Sync Preferences Modal)
-Click **`[⚙️ Sync Settings]`** in the top right of the Cockpit to adjust synchronization:
-* **Three Flexible Sync Strategies**:
-  * **⚡ Instant Render (SWR, Recommended)**: Instantly displays local cache (0ms), silently syncing latest state in background;
-  * **📋 Manual Only (Energy Saver)**: Browse local cache only; zero background `gh` processes triggered;
-  * **⏱️ Periodic Auto Poll**: Background polling according to custom intervals while cockpit is open.
-* **Custom Polling Intervals**: Choose from 1 min / 5 mins (Default) / 15 mins / 30 mins (Energy Saver) / 1 hour / Never;
-* **Visual Cache Management**: Real-time snapshot size and timestamp visibility with one-click `[🗑️ Clear Cache]`.
-
-<p align="center">
-  <img src="./docs/images/3.png" alt="Data Sync Settings Modal" width="85%" />
-</p>
-
----
-
-## 🚀 Installation Guide
-
-### Step 1: Prerequisites
-Ensure GitHub CLI (`gh`) is installed and authenticated:
-```bash
-# Windows
-winget install --id GitHub.cli
-
-# macOS
-brew install gh
-
-# Login (one-time setup)
-gh auth login
-```
-
-### Step 2: Install into DSH
+### 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):
 
-Run in your DSH environment:
+**🔄 Data Sync Section** — tune data fetching rhythm:
+* **Two Sync Strategies**:
+  * **⚡ Instant Render (SWR, Recommended)**: Instantly displays local cache (0ms), then silently syncs the latest state within 300ms — no matter how stale the cache is, opening the panel self-heals to fresh data;
+  * **📋 Manual Only (Energy Saver)**: Browse local cache only; zero background `gh` processes triggered; click `[🔄 Refresh]` whenever you want updates.
+* **Visual Cache Management**: Real-time snapshot size and timestamp visibility with one-click `[🗑️ Clear Cache]`.
 
-```bash
-# Scenario A: DSH Desktop Edition (Desktop Profile)
-dsh plugin --profile desktop add dsh-github-flow
+**🌐 Network Proxy Section** — route all plugin traffic through your proxy:
+* **Global Scope**: Once configured, the cockpit, right-sidebar panel, all 9 Agent tool invocations, and one-click upgrades route through the proxy; when disabled, system environment proxies (`HTTPS_PROXY` etc.) or direct connections apply;
+* **Protocol Support**: `http://` / `https://` / `socks5://` / `socks5h://` (gh and npm chains natively support SOCKS5; `socks5h` delegates DNS resolution to the proxy for stronger pollution resistance; the npm version probe uses Node fetch which does not support SOCKS — it stays direct and the UI states this honestly);
+* **`[🧪 Test Connectivity]`**: One-click latency probe against the GitHub API through the current proxy;
+* **Instant Effect**: Persisted to `~/.dsh/data/dsh-github-flow/proxy.json` (auto-restored on DSH restart) — no restart, no plugin reload;
+* **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.
 
-# Scenario B: DSH Web / CLI Environment
-pnpm dsh plugin add dsh-github-flow
-```
+| 🔄 Data Sync Section | 🌐 Network Proxy Section |
+| :---: | :---: |
+| ![Settings Center · Data Sync](./docs/images/3.png) | ![Settings Center · Network Proxy](./docs/images/4.png) |
 
 ---
 
@@ -207,17 +289,15 @@ Why did the Global Cockpit take several seconds to load in earlier releases? Bec
 Initial Mount (0ms) ──────────> Instantly render local persistent snapshot
                                        │
                                        ├── SWR Mode: Idle 300ms delay, silently revalidate in background
-                                       ├── Manual Mode: Browse offline snapshot, only fetch on click [🔄 Refresh]
-                                       └── Auto Poll: Periodically update according to chosen interval (e.g., 5m/30m)
+                                       └── Manual Mode: Browse offline snapshot, only fetch on click [🔄 Refresh]
 ```
 
 ### Strategy Comparison & Recommendations:
 
 | Sync Strategy | Mechanism | Recommended Use Case |
 | :--- | :--- | :--- |
-| **⚡ Instant Render (SWR, Default)** | **0ms instantaneous mount** from local cache, silently revalidating in background. | **Recommended for all developers**. Eliminates spinner freezes, delivering seamless UX. |
+| **⚡ Instant Render (SWR, Default)** | **0ms instantaneous mount** from local cache, silently revalidating in background within 300ms — however stale the snapshot, opening the panel self-heals to fresh data. | **Recommended for all developers**. Eliminates spinner freezes, delivering seamless UX. |
 | **📋 Manual Only (Energy Saver)** | Browse local cache only; zero automated background `gh` processes. | **Battery-powered laptops, low-spec hardware, or metered networks**. Zero background waste. |
-| **⏱️ Periodic Auto Poll** | Background polls status at user-specified intervals (1m to 1h). | **Maintainer workstations & dedicated monitoring setups**. Keep tasks strictly up to date. |
 
 * **Offline Resilience (Fail-Safe)**: Even when disconnected or hitting network timeouts, **your dashboard preserves the complete snapshot for searching, navigation, and review—zero blank screens or crash popups!**
 
@@ -246,10 +326,12 @@ Works out of the box, with optional tweaks in `cordis.patch.yml` or your profile
         defaultTimeoutMs: 30000   # Command timeout in milliseconds (default 30s)
         maxOutputChars: 24000     # Safe output character ceiling (Token protection)
         maxOutputBytes: 96000     # Safe UTF-8 byte ceiling (default maxOutputChars * 4)
+        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)
         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)
 ```
 
 ---
@@ -279,6 +361,9 @@ export function apply(ctx: Context) {
 
 ---
 
+## Friendship links
+- [LINUX DO - A new ideal community](https://linux.do/)
+
 ## 📄 License
 
 Open-sourced under the [MIT License](./LICENSE). Contributions, PRs, and Issues are welcome!

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 工程环境
+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 的手和脚
 
-本插件精选聚合为 **5 大领域核心工具**，拒绝几十个无用微型工具撑爆 Agent 上下文，原生搭载 **Token 防溢出保护（默认 24KB 智能二分截断）** 与 **零参数 CWD 智能绑定**。
+本插件精选聚合为 **9 大领域核心工具**，拒绝几十个无用微型工具撑爆 Agent 上下文，原生搭载 **Token 防溢出保护（默认 24KB 智能二分截断）**、**高密度 Markdown 原生渲染（列表输出压缩 70%+ Token）** 与 **零参数 CWD 智能绑定**。
 
 ### 1. `github_pr`：PR 全生命周期管理与自动化代码审查
 > **典型对话指令**：
@@ -46,13 +82,15 @@
 > - *"检查 PR #8 的 CI 检查通过了吗？通过的话帮我 Squash 合并并删除源分支"*
 
 * **支持操作 (`action`)**：
-  * `list`：列出当前仓库开放的 PR（带作者、审查判定、CI 门禁状态）；
+  * `list`：列出当前仓库开放的 PR（带作者、审查判定、CI 门禁状态，支持 `state` / `author` / `limit` 过滤）；
   * `view`：查看指定 PR 详情、描述与元数据；
-  * `diff`：获取 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`）。
+  * `merge`：自动执行合并（支持 `squash` / `merge` / `rebase`，可指定 `delete_branch`；需 `confirm: true` 二次确认）。
 
 ---
 
@@ -64,8 +102,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 +118,13 @@
 > - *"把 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。
 
 ---
 
@@ -94,7 +135,8 @@
 > - *"查看仓库 cli/cli 的基本信息与星标数"*
 
 * **支持操作 (`action`)**：
-  * `view`：查看当前或目标仓库的元数据（默认分支、星标、描述、Visibility）；
+  * `view`：查看当前或目标仓库的元数据（默认分支、星标、描述、Topics 与开源协议）；
+  * `sync`：🆕 一键拉平 Fork 仓库与上游主干，解决贡献开源项目时 Fork 落后导致 CI 门禁失败；
   * `search_code`：跨仓库或当前仓库检索特定代码符号；
   * `search_repos`：跨全站检索 GitHub 开源仓库。
 
@@ -104,11 +146,72 @@
 > **典型对话指令**：
 > - *"调用 GitHub API 获取当前仓库最新的 Release 列表，用 jq 提取 tag 名称"*
 
-* **核心优势**：直接复用本地认证环境调用任意 REST / GraphQL API，支持 `--jq` 预过滤与 `raw` 原始响应模式，绝不因插件未封装特定接口而受限。
+* **核心优势**：直接复用本地认证环境调用任意 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 沉浸式工作台与同步设置
+## 🖥️ 原生 Web UI 沉浸式工作台与设置中心
 
 ### 1. 全局全景驾驶舱 (Global Cockpit)
 
@@ -137,47 +240,26 @@
   <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
-
-# macOS 安装
-brew install gh
-
-# 登录认证（仅需执行一次）
-gh auth login
-```
+### 3. 设置中心 (Settings Modal)
+点击全景驾驶舱右上角 **`[⚙️ 设置]`** 打开分区式设置弹窗，左侧分区导航、右侧内容独立滚动（窄屏自动折叠为横向页签）：
 
-### 步骤 2：安装插件到 DSH
-
-在 DSH 终端根据你的使用环境执行对应命令：
+**🔄 数据同步分区**——调优数据拉取节奏：
+* **两种同步策略**：
+  * **⚡ 秒开模式 (SWR, 推荐)**：打开驾驶舱立即展示上次本地缓存（0ms秒开），并在 300ms 内后台静默同步最新状态——无论缓存多旧，打开即可自愈为最新；
+  * **📋 仅在手动点击时拉取 (Manual Only)**：打开只浏览本地缓存，绝不自动触发后台 gh 进程，最省电、最省资源；想更新时点击「🔄 刷新」即可。
+* **本地缓存可视化管理**：透明查看本地快照体积与保存时间戳，支持一键 `[🗑️ 清空缓存]` 重置。
 
-```bash
-# 场景 A：DSH 桌面版 (Desktop Profile)
-dsh plugin --profile desktop add dsh-github-flow
+**🌐 网络代理分区**——让插件全部外联流量走你的代理：
+* **全局生效范围**：设置后驾驶舱、右侧栏面板、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 回环请求永不被代理劫持。
 
-# 场景 B：DSH Web / CLI 工程环境
-pnpm dsh plugin add dsh-github-flow
-```
+| 🔄 数据同步分区 | 🌐 网络代理分区 |
+| :---: | :---: |
+| ![设置中心·数据同步分区](./docs/images/3.png) | ![设置中心·网络代理分区](./docs/images/4.png) |
 
 ---
 
@@ -206,17 +288,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 +325,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         # 是否开启新版本自动检查提示（默认开启）
         updateCheckIntervalMs: 86400000 # 检查更新间隔（毫秒，默认 24 小时）
         registryUrl: ''           # 自定义私有 npm 镜像地址（留空则自动选用 npmmirror 与 npmjs）
+        proxyUrl: ''              # 代理地址预置默认值（如 'http://127.0.0.1:7890'；仅未在驾驶舱设置过时生效，界面设置优先）
 ```
 
 ---
@@ -277,6 +359,12 @@ export function apply(ctx: Context) {
 - [npm 发布与自动化 CI 发版指南](./docs/npm-publish-guide.md)
 - [架构设计与技术规范](./docs/architecture.md)
 
+
+---
+## 友情链接
+
+- [LINUX DO - 新的理想型社区](https://linux.do/)
+
 ---
 
 ## 📄 开源协议 (License)

package/docs/architecture.md

@@ -27,16 +27,26 @@
 │            │                       │                        │               │
 │            ▼                       ▼                        ▼               │
 │  ┌──────────────────┐    ┌──────────────────┐    ┌───────────────────────┐  │
-│  │  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 (闲时)│  │
 │  │  - api (逃生门)  │                            │ - /upgrade (一键自动) │  │
-│  └──────────────────┘                            └──────────┬────────────┘  │
-│                                                             │               │
-│                                                             │ HTTP API      │
+│  │  - release       │                            └──────────┬────────────┘  │
+│  │  - secret (stdin)│                                       │               │
+│  │  - skill         │                                       │ HTTP API      │
+│  │  - help (元指南) │                                       │               │
+│  └────────┬─────────┘                                       │               │
+│           │                                                 │               │
+│           ▼                                                 │               │
+│  ┌──────────────────────────────────┐                       │               │
+│  │  Markdown 渲染引擎 (renderers/)  │                       │               │
+│  │  - 列表表格化压缩 70%+ Token     │                       │               │
+│  │  - 状态徽章/超链接/转义防破损     │                       │               │
+│  │  - 高危确认卡片/敏感字段隔离      │                       │               │
+│  └──────────────────────────────────┘                       │               │
 └─────────────────────────────────────────────────────────────┼───────────────┘
                                                               │
 ┌─────────────────────────────────────────────────────────────┼───────────────┐
@@ -72,8 +82,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` 显式参数，未确认时仅返回影响评估卡片，不产生任何远端或本地副作用；
+- 密钥明文仅经子进程标准输入传递（`execFile` 的 `input` 选项），全程不出现在命令行参数、进程列表与工具输出中；渲染层对 secret 输出采用独立实现，从结构上隔离「绝不渲染 value 字段」这条安全红线。
+
 ### 2.4 原生浅色/深色主题自适应与快捷操作网格
 - 全面对齐 DSH 官方 DSW 语义设计变量，基于 `body[data-ds-dark-theme]` 驱动无闪烁双模式切换；
 - 右侧栏快捷操作栏彻底废弃失效的阻塞弹窗，全面采用官方直达模式（查看所有 Issues、查看 PRs、Compare / New Issue），享有 100% 官方富文本体验。