dsh-github-flow

dsh plugin --profile web add dsh-github-flow

DSH GitHub Flow (dsh-github-flow)

<p align="center">

<a href="https://www.npmjs.com/package/dsh-github-flow"><img src="https://img.shields.io/npm/v/dsh-github-flow.svg?style=flat-square&color=0969da" alt="npm version" /></a>

<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>让 DeepSeek Harness Agent 拥有操作 GitHub 的原生手和脚，为人机协作打造沉浸式 GitHub 工作台。</b><br>

原生复用宿主机 <code>gh</code> CLI 安全登录凭据，告别 Personal Access Token 泄露；深度打通本地 Git 工作区与云端仓库协作，兼具 <b>19 大领域 Agent 核心工具（106 个 action，覆盖 PR 审查/Issue 任务/Actions 工作流与构建缓存治理/免 clone 读文件/分支规则集策略排障/代码片段 Gist/标签与全局待办大盘/密钥与变量管理/智能体任务会话/社区 Discussions 讨论/Projects v2 看板/云端 Codespaces/运行时遥测与自愈健康度）</b>、<b>人类 Slash 快捷指令</b>、<b>Web UI 全景工作台</b> 与 <b>一键自动跨平台无缝升级</b>。

</p>

<p align="center">

<b>简体中文</b> | <b><a href="./README.en.md">English</a></b>

</p>

---

🎯 为什么需要 dsh-github-flow？

在日常使用 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 矩阵，一目了然。

分支切换与本地改动感知 · 切分支需切回终端敲命令，且右侧栏无法感知本地代码暂存与提交改动，数据频频过时。 · 界面安全切分支 + 本地 Git 实时感知：支持关键词过滤与未提交改动安全拦截；基于定向 .git 监听实现毫秒级自动对齐。

首屏加载与性能等待 · 每次打开全景驾驶舱全屏白屏卡死转圈 8~15 秒，等待所有网络与子进程请求返回。 · SWR 0ms 瞬间秒开 + 云端定时同步：打开立即呈现本地快照；支持 SWR 秒开、云端定时轮询（5~60m 息屏避让）与纯手动刷新三选一互斥模式。

插件维护与升级 · 插件更新全靠开发者去 npm 碰运气看版本号，命令复杂不敢升。 · 闲时静默探测 + Web 一键自动升级：双源极速探测，自动适配 Mac/Windows 跨平台命令，界面点击即升。

---

🚀 安装指南

步骤 1：前置准备（若已安装可跳过）

确保你的机器上已安装 GitHub CLI (gh) 并已登录：

# Windows 安装
winget install --id GitHub.cli

# macOS 安装
brew install gh

# 登录认证（仅需执行一次）
gh auth login

步骤 2：安装插件到 DSH

在 DSH 终端根据你的使用环境执行对应命令：

# 场景 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 的手和脚

本插件精选聚合为 19 大领域核心工具（106 个 action），拒绝几十个无用微型工具撑爆 Agent 上下文，原生搭载 Token 防溢出保护（默认 24KB 智能二分截断）、高密度 Markdown 原生渲染（列表输出压缩 70%+ Token）、OAuth Scope 缺失单行自愈引导 与 零参数 CWD 智能绑定。

0. github_task：任务级原语（🆕 v0.7.0 新增）

典型对话指令：

- "帮我审一下 PR #12，重点看安全问题"

- "CI 为什么挂了？"

- "下一个版本该发多少号？notes 写一下"

上面 18 个领域工具是一张动词表（list / view / diff / checks / review…），而用户说的是任务。github_task 把三件最常反复走的事各封装成一次调用，返回已裁剪、可直接执行的结论包：

summary（结论，≤1.5KB） + facts（结构化事实） + nextActions（可执行下一步） + cost（字符数 / gh 调用数 / 耗时）

• review_pr：一次拿齐 PR 元数据 + head SHA + 变动文件 diff（按 budget_chars 裁剪）+ CI 三态 + 仓库 AGENTS.md 审查规则 + 既有行级评论数。
• focus: 'security' | 'correctness' | 'perf' | 'style' 只影响结论里的提示语，不改变取数。
• 默认只读；要写回行级评注必须 write: true, confirm: true（闸门会先返回确认载荷）。
• diagnose_ci：run_id 或 pr_number 二选一 → 定位失败 job/step → 按框架锚点萃取失败日志 → 汇总疑似相关文件。日志被截断时 truncated.totalUnknown = true，不要据此判断「就这些失败」。
• prepare_release：读最近 tag 以来的提交 → 按 Conventional Commits 归类 → 推导 SemVer（breaking→major / feat→minor / 其余→patch）→ 生成 notes 草稿 + 发版体检（工作区干净 / 同步远端 / CI 绿）。
• 本原语不会打 tag、不会 push、不会创建 Release：发版是人的决定，它只把「该发什么版本、notes 长什么样」准备好，并在 nextActions 里给出可直接执行的命令。

档位建议：toolsets: ['core'] 就是「3 个任务替代 15 个领域工具」（github_task + github_repo + github_help，schema 仅约 4,400 字符，比全量省 84%）。需要细粒度控制时再显式挂 github_pr / github_run——原语是快捷方式，不是唯一入口。

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 预演，支持 attach_images 上传本地附件）；
• edit：🆕 编辑 PR 标题、描述与关联元数据，支持附加本地图片；
• comment：🆕 向指定 PR 追加讨论评论与审查意见，支持附加本地图片；
• checkout：🆕 把 PR 代码检出到本地分支，Agent 可直接在本地工作区跑测试验证改动（检出前校验工作区干净度；默认不重置已有同名分支，需要重置须显式传 force: true + confirm: true）；
• status：🆕 查看当前分支关联 PR 的合并冲突状态（CLEAN / CONFLICT）；
• review：提交代码审查意见（APPROVE, REQUEST_CHANGES, COMMENT）；
• 🆕 review + comments（行级评注写入，v0.7.0 新增）：gh pr review 本身没有行级参数，本版本新增 comments 数组走 POST /pulls/{n}/reviews，一次提交多条挂在具体代码行上的评注。不传 comments 时行为与旧版逐字节一致（仍走 gh pr review），默认零写回。

    // github_pr(action:'review', pr_number:12, review_decision:'COMMENT',
    //            body:'整体说明', comments:[{ path:'src/a.ts', line:42, body:'这里要加锁' }])
    // 可选字段：side('LEFT'|'

…(truncated)