dsh-github-flow 0.4.0 → 0.6.0

package/lib/types.d.ts

@@ -68,6 +68,18 @@ export interface GhExecutionOptions {
      * 暴露在进程命令行（ps / 任务管理器 / 审计日志可见）的传入通道。
      */
     stdin?: string;
+    /**
+     * 单次调用的输出字符上限覆盖（默认沿用实例配置的 maxOutputChars=24000）。
+     *
+     * 为什么需要按调用覆盖：这个默认值是按「喂给模型上下文的工具输出」调校的，
+     * 目的是防 Token 爆窗。但有些输出是**程序化消费**的——例如 PR 全量 Unified Diff
+     * 会被切片成按文件索引、前端一次只渲染一个文件，永远不会整段进模型上下文。
+     * 对这类调用沿用 24KB 会静默截断真实数据（实测一个普通 PR 的 diff 已达 39KB，
+     * 被截断后后半数文件点开皆空）。消费者不同，阈值就该不同。
+     */
+    maxOutputChars?: number;
+    /** 单次调用的输出 UTF-8 字节上限覆盖，语义同 maxOutputChars */
+    maxOutputBytes?: number;
 }
 export interface GhResult<T = unknown> {
     ok: boolean;
@@ -78,6 +90,22 @@ export interface GhResult<T = unknown> {
     truncated?: boolean;
     /** 二进制模式下的字节长度（data 为 Buffer 时存在） */
     binaryBytes?: number;
+    /**
+     * 失败语义分类（仅 ok=false 时存在）。
+     *
+     * 为什么挂在结果上而不是让调用方自己 parse error 文本：调用方散落在
+     * 各工具与路由里，重复实现文本匹配必然漂移；分类规则只应有一份事实源
+     * （src/executor/error-classifier.ts）。上层据此决定「重试 / 回退快照 / 直接降级」。
+     */
+    errorKind?: 'transient' | 'deterministic' | 'unknown';
+    /**
+     * 权限不足时的可操作处置指引（仅 errorKind=deterministic 且命中权限特征时存在）。
+     *
+     * 为什么单独成字段而不直接拼进 error：error 是「发生了什么」，
+     * 这是「接下来怎么做」。工具层可以选择只抛 error（静默场景）
+     * 或把两者一起抛给模型（需要模型自愈的场景）。
+     */
+    permissionRemedy?: string;
 }
 export interface AuthInstallGuide {
     /** 推荐包管理器命令，例如 Windows 下 "winget install --id GitHub.cli" */
@@ -107,6 +135,47 @@ export interface AuthStatus {
     /** 本地是否已检测到持久化凭据（如 hosts.yml 或 Keyring） */
     hasLocalToken?: boolean;
 }
+/**
+ * 当前账号对仓库的权限档位（gh `viewerPermission` 字段的取值域）。
+ * 只读（READ / TRIAGE）意味着任何写操作都会被 GitHub 拒绝，
+ * UI 应据此在操作前给出提示，而不是让用户点了才吃 403。
+ */
+export type ViewerPermission = 'ADMIN' | 'MAINTAIN' | 'WRITE' | 'TRIAGE' | 'READ';
+/**
+ * 工作区的远程布局分类（离线解析得出，用于确定「该用哪个 remote 的身份」）。
+ *
+ * 为什么要分类：混合布局下若按 `.git/config` 的书写顺序选 remote，
+ * 同一个工作区在两次 `git remote` 操作后可能解析出不同仓库。
+ * 分类后每种布局的处置规则固定，与书写顺序无关。
+ */
+export type RepoLayoutKind = 
+/** 全部 remote 都是 github.com */
+'github-only'
+/** 含 GitHub remote，但 git 选中的那个不是 GitHub */
+ | 'github-mixed'
+/** 无任何 GitHub remote（全 GHE 或其他 host） */
+ | 'no-github'
+/** 无 remote */
+ | 'no-remote';
+/**
+ * 关联仓库角色标识：
+ * - fork: 属于当前登录用户的个人复刻仓库
+ * - upstream: 社区上游主干仓库（名为 upstream 或作为 parent）
+ * - origin: 默认 origin 远程仓库
+ * - parent: 上游源仓库（在线识别自 repo.parent，本地尚未添加 remote）
+ * - remote: 其他自定义名称的远程仓库
+ */
+export type AssociatedRepoRole = 'origin' | 'upstream' | 'fork' | 'parent' | 'remote';
+/**
+ * 当前工作区可切换的关联 GitHub 仓库项（供仓库切换器下拉菜单消费）。
+ */
+export interface AssociatedRepoItem {
+    nameWithOwner: string;
+    remoteName?: string;
+    url: string;
+    isCurrent: boolean;
+    role: AssociatedRepoRole;
+}
 export interface RepoMetadata {
     nameWithOwner: string;
     name: string;
@@ -116,6 +185,32 @@ export interface RepoMetadata {
     description?: string;
     isPrivate?: boolean;
     url?: string;
+    stargazerCount?: number;
+    forkCount?: number;
+    /** 是否为 fork（影响 star 取谁、是否提示可查看上游） */
+    isFork?: boolean;
+    /**
+     * fork 的上游。
+     * gh 的 `parent` 只返回骨架（id/name/owner.login），nameWithOwner 需自行拼接；
+     * 上游 star 数拿不到（`--json` 不支持嵌套子字段），故此处不含热度字段。
+     */
+    parent?: {
+        nameWithOwner: string;
+        url?: string;
+    };
+    /**
+     * 当前账号对该仓库的权限。
+     * 离线解析时为 undefined——**不猜测**：猜错会导致 UI 给出错误的操作许可。
+     */
+    viewerPermission?: ViewerPermission;
+    /** 远程布局分类（仅离线解析产生，供 UI 与诊断区分场景） */
+    layout?: RepoLayoutKind;
+    /**
+     * 当前工作区可供用户手动切换的关联仓库列表。
+     * 包含：本地 Git 配置的全部 GitHub remote (origin, upstream 等) 及在线 parent。
+     * 仅当数量 > 1 时 UI 渲染切换控件，单仓库场景保持零噪音。
+     */
+    associatedRepos?: AssociatedRepoItem[];
 }
 /** Git 分支详情项（供分支切换器下拉列表消费） */
 export interface GitBranchItem {
@@ -198,6 +293,105 @@ export interface PrItem {
     url: string;
     updatedAt: string;
 }
+/** PR 变动文件详情项 */
+export interface PrFileItem {
+    path: string;
+    additions: number;
+    deletions: number;
+    changeType?: string;
+}
+/** PR 评论项 */
+export interface PrCommentItem {
+    id: string;
+    author: {
+        login: string;
+        avatarUrl?: string;
+    };
+    authorAssociation?: string;
+    body: string;
+    createdAt: string;
+    url: string;
+}
+/** PR 审查记录项 */
+export interface PrReviewItem {
+    id: string;
+    author: {
+        login: string;
+    };
+    state: string;
+    body: string;
+    submittedAt: string;
+}
+/**
+ * PR 行级审查评论项（代码行上的评论，区别于 Issue 级讨论）。
+ *
+ * 为什么必须单列：`gh pr view --json comments` 只返回**对话区**的 issue-level 评论，
+ * 完全不包含挂在具体代码行上的 review comment。实测 cli/cli#14752 有 10 条行级评论，
+ * 而 `--json comments` 一条都拿不到——必须走
+ * `GET /repos/{owner}/{repo}/pulls/{number}/comments` 独立通道。
+ *
+ * 不做的部分：不把评论按行号精确嵌进 diff 的 hunk 中间（需反查 hunk 偏移，
+ * 多行/折叠上下文下极易错位）。改为在文件级 diff 下方按行号列出，信息完整且确定。
+ */
+export interface PrLineCommentItem {
+    id: string;
+    /** 所属文件路径，与 fileDiffs 的键一致 */
+    path: string;
+    /** 评论锚定的行号（新文件侧）；纯删除行可能为 null */
+    line: number | null;
+    side?: string;
+    author: {
+        login: string;
+    };
+    body: string;
+    createdAt: string;
+}
+/** PR 完整详情与差异数据契约（供 PrDetailModal 在线审阅消费） */
+export interface PrDetailData {
+    number: number;
+    title: string;
+    state: 'OPEN' | 'CLOSED' | 'MERGED';
+    isDraft: boolean;
+    url: string;
+    createdAt: string;
+    updatedAt: string;
+    author: {
+        login: string;
+        avatarUrl?: string;
+    };
+    headRefName: string;
+    baseRefName: string;
+    headRepoOwner?: string;
+    body: string;
+    reviewDecision?: string;
+    statusCheckRollup?: any;
+    additions: number;
+    deletions: number;
+    files: PrFileItem[];
+    comments: PrCommentItem[];
+    reviews: PrReviewItem[];
+    /**
+     * 行级审查评论（挂在具体代码行上的 review comment）。
+     * 与 comments 是**两套独立数据源**：comments 来自对话区，lineComments 来自
+     * /pulls/{n}/comments。拉取失败时降级为空数组，不阻塞主详情。
+     */
+    lineComments?: PrLineCommentItem[];
+    /** 按文件相对路径切片索引的 Git Unified Diff 字典 */
+    fileDiffs: Record<string, string>;
+    /**
+     * 为什么不回传 fullDiff 原文：`fileDiffs` 已经是全量 diff 的等价切分
+     * （每段拼起来就是原文），再附带一份原文会让 HTTP 响应体整整翻倍。
+     * 实测一个普通 PR 的 diff 就有 39KB，2MB 上限下翻倍意味着 4MB JSON——
+     * 白占带宽、白占浏览器内存、白耗 JSON.parse 时间，且没有任何消费方。
+     * 原文仅在服务端用于切片，切片完即丢弃。
+     */
+    /**
+     * diff 是否被输出阈值截断。
+     * 为什么必须透出：超巨量 PR 仍可能触顶，此时部分文件拿不到 diff。
+     * 静默展示「该文件无差异」会让用户误以为代码没改动——必须显式提示。
+     */
+    diffTruncated?: boolean;
+}
 /**
  * Issue 分类维度契约：
  * - reported: 用户提起的（他人向我名下项目或本仓库提交的 Issue 反馈）
@@ -205,6 +399,107 @@ export interface PrItem {
  * - created: 我创建的（由当前账号亲自发起的 Issue）
  */
 export type IssueCategory = 'reported' | 'assigned' | 'created';
+/** Issue 评论项（在线查看弹窗的讨论时间线消费） */
+export interface IssueCommentItem {
+    id: string;
+    author: {
+        login: string;
+        avatarUrl?: string;
+    };
+    authorAssociation?: string;
+    body: string;
+    createdAt: string;
+    url: string;
+    /**
+     * GitHub 侧被折叠/隐藏的评论（垃圾、攻击性内容等）。
+     * 为什么必须透出：实测 cli/cli#1 的评论带 `isMinimized: true, minimizedReason: "SPAM"`，
+     * 若照常渲染成普通讨论，用户会把垃圾内容当成真实技术意见。
+     */
+    isMinimized?: boolean;
+    minimizedReason?: string;
+    includesCreatedEdit?: boolean;
+}
+/**
+ * Issue 关联的 PR 引用。
+ *
+ * 字段集受限于 gh 的实际返回：实测 `gh issue view --json closedByPullRequestsReferences`
+ * 的节点只有 `id / number / repository / url`，**没有 title 与 state**。
+ * UI 因此只渲染 `#number` 链接，不得假设更多字段存在。
+ */
+export interface IssueLinkedPrRef {
+    number: number;
+    url: string;
+    /** `owner/repo`；跨仓关联时与 Issue 自身仓库不同 */
+    repository?: string;
+}
+/** Issue 里程碑（实测形态：number/title/description/dueOn，无 state） */
+export interface IssueMilestoneInfo {
+    number?: number;
+    title: string;
+    /** ISO 时间；未设置截止日时为缺省 */
+    dueOn?: string;
+}
+/** 子议题完成度摘要（gh `subIssuesSummary` 的直接映射） */
+export interface IssueSubIssuesSummary {
+    completed: number;
+    total: number;
+}
+/**
+ * Issue 完整详情数据契约（供 IssueDetailModal 在线查看消费）。
+ *
+ * 为什么不复用 `IssueItem`：列表项只需要渲染一行卡片，字段刻意精简；
+ * 详情需要正文、评论时间线、里程碑、子议题等重字段，混在一起会让
+ * 全局概览的缓存与快照体积翻数倍（每条 Issue 都拖着全部评论）。
+ */
+export interface IssueDetailData {
+    number: number;
+    title: string;
+    state: 'OPEN' | 'CLOSED';
+    /** COMPLETED / NOT_PLANNED / REOPENED / ''（实测空串形态存在） */
+    stateReason?: string;
+    url: string;
+    createdAt: string;
+    updatedAt: string;
+    closedAt?: string;
+    author: {
+        login: string;
+        avatarUrl?: string;
+    };
+    body: string;
+    labels: Array<{
+        name: string;
+        color?: string;
+        description?: string;
+    }>;
+    assignees: Array<{
+        login: string;
+    }>;
+    milestone?: IssueMilestoneInfo;
+    isPinned?: boolean;
+    issueType?: string;
+    comments: IssueCommentItem[];
+    linkedPrs: IssueLinkedPrRef[];
+    subIssues?: IssueSubIssuesSummary;
+    /**
+     * 正文与评论中识别到的图片 URL（与 github_issue(view_images) 同源提取）。
+     *
+     * 为什么只给清单不在弹窗内联渲染：图片可能来自任意 https 外域，
+     * 在面板里直接 `<img src>` 会把宿主页面 Referer/来源暴露给第三方，
+     * 也绕过了插件的域名白名单防线。UI 只展示「附件 N 张」并给外链。
+     */
+    images: string[];
+    /**
+     * 是否发生过字段集降级。
+     * 为什么需要：老版本 gh 遇到未知 JSON 字段会整体失败（实测
+     * `Unknown JSON field: "closedAt"`），此时回退到 BASE 字段集重试；
+     * 该标记供排查「为什么没看到里程碑/关联 PR」这类差异，不弹错。
+     *
+     * 注意：不设 truncated 标记——响应被输出阈值截断时 executor 直接返回
+     * `ok:false` + 浏览器直达链接，绝不会产出「零评论」的空详情对象，
+     * 因此该失败语义不需要在数据契约里再表达一次。
+     */
+    fieldsDegraded?: boolean;
+}
 export interface IssueStats {
     total: number;
     reported: number;
@@ -253,6 +548,14 @@ export interface GitHubOverviewData {
     networkError?: boolean;
     /** 网络异常的原因或提示 */
     networkErrorReason?: string;
+    /**
+     * 确定性降级说明（非错误）。
+     *
+     * 为什么与 networkError 分开：仓库关闭 Issues、未启用 Discussions 这类
+     * 「配置事实」不是故障，不该触发网络告警横幅与重试。它们只需要在面板上
+     * 安静地说明一句「该仓库未开启 Issues」，让用户知道空列表是正常的。
+     */
+    notices?: string[];
     /** 插件版本与升级信息（由内存缓存快速读取，不阻塞首屏业务） */
     updateInfo?: UpdateInfo;
     /** 本地 Git 状态（ahead/behind/dirty，remote-tracking 快照语义）；非 Git 工作区为 undefined */
@@ -276,6 +579,17 @@ export interface GitHubOverviewData {
     } | null;
     /** 当前工作区的 Git 分支列表（供右侧栏分支选择器 0ms 秒开） */
     branches?: GitBranchesResult | null;
+    /**
+     * 单仓库 PR 列表是否触及条数上限（仅触顶时下发）。
+     *
+     * 为什么必须透出：查询已放宽为 `--state all`，列表按 number 降序取前 N 条，
+     * 历史 PR 超过上限时界面会静默少显示——用户切到「Closed」看到几条
+     * 就会误以为仓库只有这么几个已关闭 PR，无法区分「就这么多」与「被截断了」。
+     * 与全局面板的 prsTruncated 同一语义。
+     */
+    prsTruncated?: boolean;
+    /** 单仓库 Issue 列表是否触及条数上限（语义同 prsTruncated） */
+    issuesTruncated?: boolean;
 }
 export interface UserRepoItem {
     name: string;
@@ -326,14 +640,28 @@ export interface GlobalOverviewData {
     myPrs: Array<{
         number: number;
         title: string;
+        /**
+         * PR 状态。为什么必须下发：主面板默认展示「全部」而非仅 open
+         * （实测账号可能零 open PR，只查 open 会恒为空白），
+         * 前端要靠这个字段做状态胶囊筛选与徽章标注。
+         */
+        state?: 'OPEN' | 'CLOSED' | 'MERGED';
         repository: {
             nameWithOwner: string;
         };
         url: string;
         updatedAt: string;
+        isDraft?: boolean;
     }>;
     myIssues: GlobalIssueItem[];
     issueStats?: IssueStats;
+    /**
+     * PR 检索是否触及上限（仅触顶时下发）。
+     * 为什么必须透出：去掉 open 过滤后按 updatedAt 降序返回最近 N 条，
+     * 若账号历史 PR 超过上限，界面会静默少显示，用户无法区分
+     * 「列表到此为止」与「数据没取到」。
+     */
+    prsTruncated?: boolean;
     lastUpdated: string;
     error?: string;
     /** 网络是否发生异常（超时、连接拒绝、代理阻断等） */
@@ -342,6 +670,11 @@ export interface GlobalOverviewData {
     networkErrorReason?: string;
     /** 工作区矩阵读取失败的原因。区分「没有工作区」与「读不到工作区」，避免把故障显示成空状态 */
     workspaceError?: string;
+    /**
+     * 确定性降级说明（非错误）：仓库关闭 Issues、未启用 Discussions 等配置事实。
+     * 与 networkError 互斥——它不是故障，不该触发告警横幅与重试。
+     */
+    notices?: string[];
     /** 插件版本与升级信息（由内存缓存快速读取，不阻塞首屏业务） */
     updateInfo?: UpdateInfo;
 }
@@ -363,11 +696,13 @@ export interface UpdateInfo {
     checkedAt: number;
 }
 export type UpgradeState = 'idle' | 'upgrading' | 'success' | 'failed';
+export type UpgradeErrorType = 'MINIMUM_RELEASE_AGE_VIOLATION' | 'TIMEOUT' | 'UNKNOWN';
 export interface UpgradeStatusResult {
     state: UpgradeState;
     targetVersion?: string;
     message?: string;
     log?: string;
+    errorType?: UpgradeErrorType;
     startedAt?: number;
     completedAt?: number;
     /** 识别到的宿主环境类型：desktop 为桌面版，web 为网页/CLI版 */
@@ -377,6 +712,7 @@ export interface UpgradeExecutionResult {
     ok: boolean;
     message: string;
     needRestart: boolean;
+    errorType?: UpgradeErrorType;
     log?: string;
     environment?: 'desktop' | 'web';
 }

package/lib/ui/commit-modal.js

@@ -36,13 +36,16 @@ export function CommitDetailModal(props) {
     if (!effectiveBody && !effectiveStat && fetchedDetail) {
         effectiveStat = fetchedDetail;
     }
+    var parsedStat = React.useMemo(() => {
+        return effectiveStat && typeof parseGitStatText === "function" ? parseGitStatText(effectiveStat) : null;
+    }, [effectiveStat]);
     return h("div", {
         className: "dsh-github-modal-overlay",
         onClick: props.onClose,
         style: { zIndex: 100000 },
     }, h("div", {
         className: "dsh-github-modal-dialog",
-        style: { width: "94%", maxWidth: "460px", maxHeight: "84vh", display: "flex", flexDirection: "column", overflow: "hidden" },
+        style: { width: "94%", maxWidth: "520px", maxHeight: "86vh", display: "flex", flexDirection: "column", overflow: "hidden" },
         onClick: function (e) { e.stopPropagation(); },
     }, h("div", { className: "dsh-github-modal-header", style: { flexShrink: 0 } }, h("div", { style: { display: "flex", alignItems: "center", gap: "8px" } }, renderGitIcon(15, "#1296db"), h("h3", { style: { margin: 0, fontSize: "14px", fontWeight: 600 } }, "提交详情")), h("button", {
         style: { background: "none", border: "none", cursor: "pointer", fontSize: "18px", color: "var(--dsw-alias-label-secondary, #656d76)", padding: "0 4px" },
@@ -65,22 +68,149 @@ export function CommitDetailModal(props) {
             },
         }, effectiveBody)
         : null, effectiveStat
-        ? h("div", null, h("div", { style: { fontSize: "11px", fontWeight: 600, marginBottom: "4px", opacity: 0.8 } }, "📁 文件变更统计:"), h("pre", {
-            className: "dsh-github-commit-pre",
+        ? h("div", { style: { display: "flex", flexDirection: "column", gap: "6px" } }, h("div", {
             style: {
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "space-between",
                 fontSize: "11px",
-                lineHeight: "1.5",
-                whiteSpace: "pre-wrap",
-                wordBreak: "break-word",
-                margin: 0,
-                maxHeight: "34vh",
-                overflowY: "auto",
-                padding: "8px 10px",
-                borderRadius: "6px",
-                background: "var(--dsw-alias-bg-module-platform, #f6f8fa)",
-                border: "1px solid var(--dsw-alias-border-l2, #e1e4e8)",
+                fontWeight: 600,
             },
-        }, effectiveStat))
+        }, h("div", { style: { opacity: 0.85, display: "flex", alignItems: "center", gap: "6px" } }, "📁 文件变更统计", parsedStat?.summary
+            ? h("span", { style: { opacity: 0.65, fontWeight: 400 } }, `(${parsedStat.summary.filesChanged} 个文件)`)
+            : parsedStat?.files
+                ? h("span", { style: { opacity: 0.65, fontWeight: 400 } }, `(${parsedStat.files.length} 个文件)`)
+                : null), parsedStat?.summary
+            ? h("div", { style: { display: "flex", gap: "6px", fontFamily: "monospace", fontWeight: 600 } }, parsedStat.summary.insertions > 0
+                ? h("span", {
+                    style: {
+                        color: "var(--dsw-alias-state-success-primary, #1a7f37)",
+                        backgroundColor: "var(--dsw-alias-state-success-subtle, rgba(46,160,67,0.12))",
+                        padding: "1px 6px",
+                        borderRadius: "10px",
+                    },
+                }, `+${parsedStat.summary.insertions}`)
+                : null, parsedStat.summary.deletions > 0
+                ? h("span", {
+                    style: {
+                        color: "var(--dsw-alias-state-error-primary, #cf222e)",
+                        backgroundColor: "var(--dsw-alias-state-error-subtle, rgba(248,81,73,0.12))",
+                        padding: "1px 6px",
+                        borderRadius: "10px",
+                    },
+                }, `-${parsedStat.summary.deletions}`)
+                : null)
+            : null), parsedStat && parsedStat.files && parsedStat.files.length > 0
+            ? h("div", {
+                className: "dsh-github-stat-list",
+                style: {
+                    borderRadius: "6px",
+                    border: "1px solid var(--dsw-alias-border-l2, #e1e4e8)",
+                    background: "var(--dsw-alias-bg-module-platform, #f6f8fa)",
+                    maxHeight: "36vh",
+                    overflowY: "auto",
+                    display: "flex",
+                    flexDirection: "column",
+                },
+            }, parsedStat.files.map(function (f, idx) {
+                var diffBlocks = [];
+                if (!f.isBinary && f.total > 0) {
+                    var totalRatio = f.additions + f.deletions;
+                    var addBlocks = totalRatio > 0 ? Math.round((f.additions / totalRatio) * 5) : 0;
+                    var delBlocks = totalRatio > 0 ? Math.round((f.deletions / totalRatio) * 5) : 0;
+                    if (f.additions > 0 && addBlocks === 0)
+                        addBlocks = 1;
+                    if (f.deletions > 0 && delBlocks === 0)
+                        delBlocks = 1;
+                    while (addBlocks + delBlocks > 5) {
+                        if (addBlocks > delBlocks)
+                            addBlocks--;
+                        else
+                            delBlocks--;
+                    }
+                    var neutralBlocks = Math.max(0, 5 - addBlocks - delBlocks);
+                    for (var bi = 0; bi < addBlocks; bi++) {
+                        diffBlocks.push(h("span", { key: "a" + bi, style: { width: "3px", height: "8px", borderRadius: "1px", backgroundColor: "var(--dsw-alias-state-success-primary, #1a7f37)" } }));
+                    }
+                    for (var bj = 0; bj < delBlocks; bj++) {
+                        diffBlocks.push(h("span", { key: "d" + bj, style: { width: "3px", height: "8px", borderRadius: "1px", backgroundColor: "var(--dsw-alias-state-error-primary, #cf222e)" } }));
+                    }
+                    for (var bk = 0; bk < neutralBlocks; bk++) {
+                        diffBlocks.push(h("span", { key: "n" + bk, style: { width: "3px", height: "8px", borderRadius: "1px", backgroundColor: "var(--dsw-alias-border-subtle, rgba(0,0,0,0.15))" } }));
+                    }
+                }
+                return h("div", {
+                    key: idx,
+                    className: "dsh-github-stat-row",
+                    style: {
+                        display: "flex",
+                        alignItems: "center",
+                        justifyContent: "space-between",
+                        padding: "6px 10px",
+                        fontSize: "11px",
+                        lineHeight: "1.4",
+                        borderBottom: idx < parsedStat.files.length - 1 ? "1px solid var(--dsw-alias-border-subtle, rgba(0,0,0,0.06))" : "none",
+                        gap: "8px",
+                    },
+                    title: f.path + (f.isBinary ? " (二进制文件)" : ` (+${f.additions}, -${f.deletions})`),
+                }, h("div", {
+                    style: {
+                        fontFamily: "ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, monospace",
+                        overflow: "hidden",
+                        textOverflow: "ellipsis",
+                        whiteSpace: "nowrap",
+                        flex: 1,
+                        minWidth: 0,
+                        color: "var(--dsw-alias-label-primary, #1f2328)",
+                    },
+                }, f.path), h("div", {
+                    style: {
+                        display: "flex",
+                        alignItems: "center",
+                        gap: "6px",
+                        flexShrink: 0,
+                        fontFamily: "monospace",
+                        fontWeight: 600,
+                    },
+                }, f.isBinary
+                    ? h("span", { style: { opacity: 0.6, fontSize: "10px" } }, "二进制")
+                    : [
+                        f.additions > 0
+                            ? h("span", {
+                                key: "add",
+                                style: { color: "var(--dsw-alias-state-success-primary, #1a7f37)" },
+                            }, `+${f.additions}`)
+                            : null,
+                        f.deletions > 0
+                            ? h("span", {
+                                key: "del",
+                                style: { color: "var(--dsw-alias-state-error-primary, #cf222e)" },
+                            }, `-${f.deletions}`)
+                            : null,
+                        diffBlocks.length > 0
+                            ? h("div", {
+                                key: "bar",
+                                style: { display: "flex", gap: "1px", marginLeft: "2px", alignItems: "center" },
+                            }, ...diffBlocks)
+                            : null,
+                    ]));
+            }))
+            : h("pre", {
+                className: "dsh-github-commit-pre",
+                style: {
+                    fontSize: "11px",
+                    lineHeight: "1.5",
+                    whiteSpace: "pre-wrap",
+                    wordBreak: "break-word",
+                    margin: 0,
+                    maxHeight: "34vh",
+                    overflowY: "auto",
+                    padding: "8px 10px",
+                    borderRadius: "6px",
+                    background: "var(--dsw-alias-bg-module-platform, #f6f8fa)",
+                    border: "1px solid var(--dsw-alias-border-l2, #e1e4e8)",
+                },
+            }, effectiveStat))
         : null, !effectiveBody && !effectiveStat
         ? (fetchingDetail
             ? h("div", { style: { fontSize: "12px", opacity: 0.7, padding: "8px 0" } }, "⏳ 正在获取详细变更说明…")

package/lib/ui/help-modal.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 独立沉浸式指南大窗口组件 (Dedicated Large Reader Modal)
+ *
+ * 核心设计理由与交互契约：
+ * 1. 彻底从设置小窗口剥离，打造 920px 宽屏、85vh 高度的沉浸式阅读视界；
+ * 2. 深度适配 DSH 主题系统，全套样式基于 CSS 类与主题变量，支持深色 (data-ds-dark-theme) 与浅色无缝自适应；
+ * 3. 拒绝技术自嗨清单，从用户行动视角组织：3分钟快速上手、Agent实战Prompt、双界面图解与常见排错；
+ * 4. 宽屏卡片排列，配备 Prompt 一键复制到剪贴板与短暂反馈气泡；
+ * 5. 监听键盘 Esc 键与遮罩点击秒关，复制完指令直接回到聊天输入框发送，零打扰、不中断工作流。
+ *
+ * 【内容与代码同步的纪律】
+ * 本文件里出现的工具数量、action 数量、Tab 名称、按钮文案，全部以当前代码为准：
+ * 工具矩阵 = src/main.ts 的 18 处 ctx.tools.register；
+ * Tab 布局 = src/client.ts 的 TAB_DEFS 与 src/ui/workspace-panel.ts 的四个标签；
+ * 若后续增删工具或 Tab，必须同步改这里，否则用户会照着过时说明去找不存在的入口。
+ */
+export declare function GithubHelpModal(props: {
+    isOpen: boolean;
+    onClose: () => void;
+    initialTab?: string;
+}): any;