dsh-github-flow 0.5.0 → 0.6.0

package/lib/tools/help.js

@@ -12,7 +12,7 @@ const KNOWLEDGE_BASE = {
 | \`github_api\` | 原生 GitHub REST/GraphQL 逃生门 | 调用任意端点、获取原始文件字节 (raw)、支持自动翻页 (paginate) |
 | \`github_release\` | 版本发布与构建资产交付 | 查看发版历史、自动生成 Release Notes、上传 .tgz 等构建产物 |
 | \`github_secret\` | CI/CD 密钥与变量管理 | 查看 NPM_TOKEN 等密钥清单、经 stdin 安全写入密文、删除密钥；kind:'variable' 管理明文变量（set/get/delete） |
-| \`github_skill\` | 跨 Agent 开源 Skills 生态发现 | 检索/预览/安装 GitHub 上的 Agent Skills (gh preview 特性) |
+| \`github_skill\` | 跨 Agent 开源 Skills 生态发现与维护 | 检索/预览/安装 GitHub 上的 Agent Skills（gh preview 特性）；\`publish\` 规范自检与发布、\`update\` 检查并同步更新已安装技能 |
 | \`github_label\` | 标签体系管理与跨仓库克隆 | 查看标签列表、创建/编辑标签、从源仓库一键 clone 标签体系、删除标签（需 confirm） |
 | \`github_ruleset\` | 分支保护规则与策略诊断 | 检查分支适用的合并策略规则 (check)、查看规则集列表与详情，权威回答“PR 为何无法合并” |
 | \`github_cache\` | Actions 构建缓存盘点与安全清理 | 查看缓存列表与体积占用、按 ID/Key 删除指定缓存、全量清空缓存（需 confirm） |
@@ -25,7 +25,9 @@ const KNOWLEDGE_BASE = {
 | \`github_help\` | 路由导航、官方语法速查与故障自愈 | 遇到不确定的操作、搜索语法或接口报错时查询用法与诊断配方 |
 
 💡 **使用准则**：优先调用高层语义工具（pr / issue / run / repo / release / secret）；当高层工具无法满足特殊接口需求时，再降级使用 \`github_api\`。
+📊 **规模口径**：18 个工具 / 103 个业务 action（不含 \`github_help\` 的 21 个查询主题与 \`github_api\` 的 4 个 HTTP method——它们不是业务动作）。
 💬 **人类指令**：聊天框支持 \`/gh status\`（大盘看板）、\`/gh upgrade\`（一键升级插件）、\`/gh help\`（快捷帮助）。
+🖥️ **可视化工作台**：最左侧 Octocat 图标打开全景驾驶舱（4 标签：本地工作区 / 我的仓库 / Pull Requests / 待办 Issues）；每个会话右侧栏有 5 个 Tab（Git / 未提交 / PR / Issues / Actions）。点击任一 PR 或 Issue 卡片可在线查看详情与评论，无需跳浏览器。
 🗺️ **命令对照**：不确定某 gh 命令对应哪个工具？\`github_help(topic: 'mapping')\` 查询完整映射表（含未覆盖域的 API 引导）。`,
     pr: `### 🔀 github_pr 详细操作指南
 
@@ -47,7 +49,9 @@ const KNOWLEDGE_BASE = {
 - **分支落后自愈**: \`github_pr(action: 'update_branch', pr_number: 123)\`
   - 将基准分支最新提交同步进 PR 分支，解决「分支落后需更新」的 CI 门禁失败。
 - **上传本地附件/图片**: \`github_pr(action: 'create', title: 'UI 重构', body: '对比图如下', attach_images: ['./before.png', './after.png'])\`
-  - 需 gh ≥ 2.99；支持 create/edit/comment 动作，单批上限 50 个文件，禁止网络 URL，与 view_images 对称闭环。`,
+  - 需 gh ≥ 2.99；支持 create/edit/comment 动作，单批上限 50 个文件，禁止网络 URL，与 view_images 对称闭环。
+- **追加评论与编辑**: \`github_pr(action: 'comment', pr_number: 123, body: 'LGTM'); github_pr(action: 'edit', pr_number: 123, body: '更新后的描述')\`
+  - 两者同样支持 \`attach_images\` 附件通道。`,
     issue: `### 🎯 github_issue 详细操作指南
 
 - **筛选 Issue**: \`github_issue(action: 'list', state: 'open' | 'closed' | 'all', labels: ['bug'], assignees: ['octocat'], limit: 20)\`
@@ -164,7 +168,13 @@ const KNOWLEDGE_BASE = {
   - \`github_skill(action: 'publish')\` —— 默认 \`--dry-run\` 模式，对本地技能目录进行 agentskills.io 合规性检查（命名规范、目录匹配、必需 frontmatter 字段等），零副作用安全自检。
   - \`github_skill(action: 'publish', fix: true)\` —— 自动清洗并剥离残留的安装元数据（\`metadata.github-*\`），修改本地文件但不发布。
   - \`github_skill(action: 'publish', tag: 'v1.0.0', dry_run: false, confirm: true)\` —— 正式发布，强制要求指定 \`tag\` 并附带 \`confirm: true\`（防无头挂起与误发布），自动创建 GitHub Release。
-- ⚠️ 若报「unknown command」，说明宿主机 gh 版本过低，需升级到 2.9x 以上。`,
+- ⚠️ 若报「unknown command」，说明宿主机 gh 版本过低，需升级到 2.9x 以上。
+
+- **检查并同步更新已安装技能**:
+  - \`github_skill(action: 'update')\` —— **默认 dry-run**，只检查哪些技能有新版本，零副作用。
+  - \`github_skill(action: 'update', dry_run: false)\` —— 真正执行同步更新。
+  - \`github_skill(action: 'update', all: true)\` —— 更新全部已安装技能（否则只处理 \`skill_names\` 指定项）。
+  - \`github_skill(action: 'update', skill_names: ['code-review', 'devops'])\` —— 定向更新指定技能。`,
     label: `### 🏷️ github_label 详细操作指南
 
 - **查看标签列表**: \`github_label(action: 'list', limit: 30, search: 'bug')\`
@@ -269,10 +279,11 @@ const KNOWLEDGE_BASE = {
 
 #### 一、已覆盖域映射（语义化 action 精确对照）
 
-**PR（github_pr，13 action）**
+**PR（github_pr，15 action）**
 | gh 命令 | 插件调用 | 备注 |
 | :--- | :--- | :--- |
-| \`gh pr list/view/create/diff/edit/comment\` | \`github_pr(action:'list'/'view'/'create'/'diff'/'edit'/'comment')\` | 高频基础操作 |
+| \`gh pr list/view/create/diff/edit/comment\` | \`github_pr(action:'list'/'view'/'create'/'diff'/'edit'/'comment')\` | 高频基础操作；edit/comment 支持 attach_images |
+| （PR 图片查看，gh 无对应命令） | \`github_pr(action:'view_images', pr_number:n)\` | 插件独有：正文+评论图片下载并转为可读图像块 |
 | \`gh pr close\` | 暂无专用 action——用 \`github_pr(action:'edit')\` 或 \`github_api(endpoint:'repos/{o}/{r}/pulls/{n}', method:'PATCH', fields:{state:'closed'})\` | 插件侧未覆盖 |
 | \`gh pr checks\` | \`github_pr(action:'checks', pr_number:n)\` | CI 状态药丸 |
 | \`gh pr review\` | \`github_pr(action:'review', review_decision:'APPROVE'…)\` | |
@@ -287,6 +298,7 @@ const KNOWLEDGE_BASE = {
 | gh 命令 | 插件调用 | 备注 |
 | :--- | :--- | :--- |
 | \`gh issue list/view/create/comment/close/reopen/edit\` | \`github_issue(action:…)\` | 基础操作 |
+| （Issue 图片查看，gh 无对应命令） | \`github_issue(action:'view_images', issue_number:n)\` | 插件独有：报障截图转图像块 |
 | \`gh issue develop\` | \`github_issue(action:'develop', branch_name:…)\` | 关联开发分支 |
 | \`gh issue delete\` | \`github_issue(action:'delete', confirm:true)\` | 物理删除（非 close） |
 | \`gh issue transfer\` | \`github_issue(action:'transfer', target_repo:…, confirm:true)\` | 跨仓库迁移 |
@@ -325,8 +337,11 @@ const KNOWLEDGE_BASE = {
 | \`gh variable list/set/get/delete\` | \`github_secret(action:…, kind:'variable')\` | CI 明文：-b 直传、get 可回显 |
 | （gh secret get 不存在） | — | GitHub 侧加密存储，物理不可读取 |
 
-**Skill（github_skill，5 action）**
-\`gh skill search/preview/install/list/publish\` → \`github_skill(action:…)\`；install 需 confirm（写磁盘）；publish 默认 dry-run 安全自检，正式发布需 tag 与 confirm。
+**Skill（github_skill，6 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh skill search/preview/install/list/publish\` | \`github_skill(action:…)\` | install 需 confirm（写磁盘）；publish 默认 dry-run 安全自检，正式发布需 tag 与 confirm |
+| \`gh skill update\` | \`github_skill(action:'update')\` | 默认 dry-run 检查；\`all:true\` 或 \`skill_names\` 定向；\`dry_run:false\` 才真正更新 |
 
 **Label（github_label，5 action）**
 | gh 命令 | 插件调用 | 备注 |

package/lib/tools/image-utils.d.ts

@@ -37,6 +37,33 @@ export declare function sniffImageMime(buf: Buffer): string | null;
 /** 图片下载护栏：按真实资源消耗计算——单图字节与目录总量，无张数截断 */
 export declare const IMG_MAX_BYTES: number;
 export declare const IMG_DIR_MAX_BYTES: number;
+export declare const IMG_DIR_LOW_WATERMARK: number;
+/**
+ * 图片落盘目录（按内容寻址命名，重复下载天然去重）。
+ *
+ * 为什么支持 DSH_IMAGE_DIR 覆盖：目录里有 LRU 淘汰，按 mtime 删最旧文件。
+ * 若测试把 13MB 假数据写进真实用户目录，淘汰就会优先命中用户更早下载的
+ * 真图（用户图 mtime 更老，排序更靠前），造成静默数据丢失。
+ * 测试必须能把目录重定向到临时区——这与 upgrade-manager 的 DSH_CLI_BIN /
+ * DSH_PROFILE_DIR 覆盖是同一套思路。
+ */
+export declare function imageStoreDir(): string;
+/** 粗略统计图片目录现有总量（遍历一次，文件数有护栏上限不会失控） */
+export declare function imageDirSize(dir: string): number;
+export interface LruEvictionResult {
+    freedBytes: number;
+    evictedCount: number;
+    evictedFiles: string[];
+}
+/**
+ * LRU 图片缓存淘汰：当目录空间不足以容纳新图片时，按最后修改时间（mtime）淘汰最旧的历史文件。
+ *
+ * 护栏纪律：
+ * 1. 保护当前批次已写入的文件（protectFiles）：避免同一批次内前一张图被后一张图立即顶替；
+ * 2. 仅淘汰历史文件：按 mtime 升序排列（最旧优先），逐一清理直到目录大小降至目标低水位；
+ * 3. 容错防御：单文件删除失败（如文件被锁定）静默跳过继续尝试下一个，绝不崩溃中断。
+ */
+export declare function evictLruImages(dir: string, neededBytes: number, protectFiles?: Set<string>, maxDirBytes?: number, targetBytes?: number): LruEvictionResult;
 export interface DownloadedImage {
     file: string;
     mimeType: string;

package/lib/tools/image-utils.js

@@ -132,12 +132,24 @@ export function sniffImageMime(buf) {
 /** 图片下载护栏：按真实资源消耗计算——单图字节与目录总量，无张数截断 */
 export const IMG_MAX_BYTES = 5 * 1024 * 1024; // 单图 5MB
 export const IMG_DIR_MAX_BYTES = 15 * 1024 * 1024; // 图片缓存目录总量 15MB
-/** 图片落盘目录（按内容寻址命名，重复下载天然去重） */
-function imageStoreDir() {
+export const IMG_DIR_LOW_WATERMARK = 10 * 1024 * 1024; // LRU 淘汰低水位目标 10MB
+/**
+ * 图片落盘目录（按内容寻址命名，重复下载天然去重）。
+ *
+ * 为什么支持 DSH_IMAGE_DIR 覆盖：目录里有 LRU 淘汰，按 mtime 删最旧文件。
+ * 若测试把 13MB 假数据写进真实用户目录，淘汰就会优先命中用户更早下载的
+ * 真图（用户图 mtime 更老，排序更靠前），造成静默数据丢失。
+ * 测试必须能把目录重定向到临时区——这与 upgrade-manager 的 DSH_CLI_BIN /
+ * DSH_PROFILE_DIR 覆盖是同一套思路。
+ */
+export function imageStoreDir() {
+    const override = (process.env.DSH_IMAGE_DIR || '').trim();
+    if (override)
+        return path.resolve(override);
     return path.join(os.homedir(), '.dsh', 'data', 'dsh-github-flow', 'images');
 }
 /** 粗略统计图片目录现有总量（遍历一次，文件数有护栏上限不会失控） */
-function imageDirSize(dir) {
+export function imageDirSize(dir) {
     let total = 0;
     try {
         for (const f of fs.readdirSync(dir)) {
@@ -150,6 +162,57 @@ function imageDirSize(dir) {
     catch { }
     return total;
 }
+/**
+ * LRU 图片缓存淘汰：当目录空间不足以容纳新图片时，按最后修改时间（mtime）淘汰最旧的历史文件。
+ *
+ * 护栏纪律：
+ * 1. 保护当前批次已写入的文件（protectFiles）：避免同一批次内前一张图被后一张图立即顶替；
+ * 2. 仅淘汰历史文件：按 mtime 升序排列（最旧优先），逐一清理直到目录大小降至目标低水位；
+ * 3. 容错防御：单文件删除失败（如文件被锁定）静默跳过继续尝试下一个，绝不崩溃中断。
+ */
+export function evictLruImages(dir, neededBytes, protectFiles = new Set(), maxDirBytes = IMG_DIR_MAX_BYTES, targetBytes = IMG_DIR_LOW_WATERMARK) {
+    const result = { freedBytes: 0, evictedCount: 0, evictedFiles: [] };
+    if (!fs.existsSync(dir))
+        return result;
+    let currentSize = imageDirSize(dir);
+    if (currentSize + neededBytes <= maxDirBytes) {
+        return result;
+    }
+    const candidates = [];
+    try {
+        const entries = fs.readdirSync(dir);
+        for (const name of entries) {
+            const fullPath = path.join(dir, name);
+            if (protectFiles.has(fullPath))
+                continue;
+            try {
+                const stat = fs.statSync(fullPath);
+                if (stat.isFile()) {
+                    candidates.push({ path: fullPath, size: stat.size, mtime: stat.mtimeMs });
+                }
+            }
+            catch { }
+        }
+    }
+    catch {
+        return result;
+    }
+    candidates.sort((a, b) => a.mtime - b.mtime);
+    for (const item of candidates) {
+        if (currentSize + neededBytes <= maxDirBytes && currentSize <= targetBytes) {
+            break;
+        }
+        try {
+            fs.unlinkSync(item.path);
+            currentSize -= item.size;
+            result.freedBytes += item.size;
+            result.evictedCount++;
+            result.evictedFiles.push(item.path);
+        }
+        catch { }
+    }
+    return result;
+}
 /**
  * 交集过滤：把调用方请求的 URL 硬约束在正文实际提取的合法清单内。
  * 为什么必须交集而非直接信任传入：image_urls 来自模型生成参数，存在幻觉或
@@ -190,6 +253,7 @@ export async function downloadImages(urls, run) {
     const images = [];
     const failures = [];
     const remaining = [];
+    const currentBatchFiles = new Set();
     let budgetExhausted = false;
     // 无张数截断：字节护栏按真实资源消耗逐张判定。触顶后仍继续遍历——
     // 剩余 URL 全部收进 remaining 供 Agent 分批续传，而非静默丢弃。
@@ -213,6 +277,11 @@ export async function downloadImages(urls, run) {
             failures.push(`${url.slice(-24)}: 内容不是图片（魔数校验失败）`);
             continue;
         }
+        // 空间护栏检查：若超出目录上限，优先触发 LRU 淘汰历史文件以腾出预算
+        if (dirSize + buf.length > IMG_DIR_MAX_BYTES) {
+            const { freedBytes } = evictLruImages(dir, buf.length, currentBatchFiles);
+            dirSize = Math.max(0, dirSize - freedBytes);
+        }
         if (dirSize + buf.length > IMG_DIR_MAX_BYTES) {
             budgetExhausted = true;
             remaining.push(url);
@@ -222,6 +291,7 @@ export async function downloadImages(urls, run) {
         const ext = mime.includes('svg') ? 'svg' : mime.split('/')[1].replace('jpeg', 'jpg');
         const file = path.join(dir, `${crypto.createHash('sha256').update(buf).digest('hex').slice(0, 16)}.${ext}`);
         fs.writeFileSync(file, buf);
+        currentBatchFiles.add(file);
         // 累计已写入量：下张图的总量护栏判定必须基于最新值（否则多图可突破上限）
         dirSize += buf.length;
         images.push({ file, mimeType: mime, url, bytes: buf.length });

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;
@@ -118,6 +187,30 @@ export interface RepoMetadata {
     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 {
@@ -200,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 反馈）
@@ -207,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;
@@ -255,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 */
@@ -278,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;
@@ -328,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;
     /** 网络是否发生异常（超时、连接拒绝、代理阻断等） */
@@ -344,6 +670,11 @@ export interface GlobalOverviewData {
     networkErrorReason?: string;
     /** 工作区矩阵读取失败的原因。区分「没有工作区」与「读不到工作区」，避免把故障显示成空状态 */
     workspaceError?: string;
+    /**
+     * 确定性降级说明（非错误）：仓库关闭 Issues、未启用 Discussions 等配置事实。
+     * 与 networkError 互斥——它不是故障，不该触发告警横幅与重试。
+     */
+    notices?: string[];
     /** 插件版本与升级信息（由内存缓存快速读取，不阻塞首屏业务） */
     updateInfo?: UpdateInfo;
 }

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

@@ -7,6 +7,12 @@
  * 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;