dsh-github-flow 0.3.0 → 0.5.0

package/lib/renderers/pr.js

@@ -0,0 +1,107 @@
+import { sanitizeCell, formatStateBadge, formatCiBadge, formatConflictBadge } from './common.js';
+/**
+ * PR 领域渲染器：负责 PR 列表高密度表格、CI Checks、分支状态与单卡详情格式化
+ */
+export function renderPrMarkdown(args, value) {
+    if (!value)
+        return '无返回内容';
+    if (value.status === 'AWAITING_CONFIRMATION') {
+        return [
+            `> ### ${value.warning || '⚠️ 高危操作拦截警告'}`,
+            `> - **影响评估**: ${value.impact || '该操作将改变远端仓库状态。'}`,
+            `> - **确认指引**: ${value.requiredAction || '如确认继续，请向用户核实并在参数中附加 `confirm: true` 重新调用。'}`,
+        ].join('\n');
+    }
+    if (typeof value.result === 'string')
+        return value.result;
+    if (typeof value.message === 'string' && !value.items) {
+        const extra = value.detail || value.output;
+        return `**${value.message}**` + (value.url ? `\n🔗 链接: ${value.url}` : '') + (extra ? `\n\`\`\`\n${extra}\n\`\`\`` : '');
+    }
+    // 1.1 PR 列表
+    if (Array.isArray(value.items) && args?.action === 'list') {
+        const list = value.items.filter(Boolean);
+        if (list.length === 0)
+            return '📭 当前仓库暂无匹配的 Pull Request。';
+        const rows = list.map((p) => {
+            const numLink = p.url ? `[#${p.number}](${p.url})` : `#${p.number}`;
+            const badge = formatStateBadge(p.state, p.isDraft);
+            const title = sanitizeCell(p.title, 55);
+            const author = p.author?.login ? `@${p.author.login}` : (typeof p.author === 'string' ? `@${p.author}` : '-');
+            const date = p.updatedAt ? p.updatedAt.slice(0, 10) : (p.mergedAt ? p.mergedAt.slice(0, 10) : '-');
+            return `| ${numLink} | ${badge} | ${title} | ${author} | ${date} |`;
+        });
+        return [
+            `**找到 ${list.length} 个 Pull Request:**\n`,
+            '| 编号 | 状态 | 标题 | 作者 | 更新日期 |',
+            '| :--- | :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 1.2 PR CI Checks
+    if (Array.isArray(value.items) && args?.action === 'checks') {
+        const list = value.items.filter(Boolean);
+        if (list.length === 0)
+            return '当前 PR 暂无 CI Checks 运行记录。';
+        const rows = list.map((c) => {
+            const name = sanitizeCell(c.name, 40);
+            // bucket 是 gh pr checks 的分类字段（pass/fail/pending/skipping/cancel），
+            // 优先于 state 呈现；state（SUCCESS/FAILURE/...）作为兜底——渲染器同步
+            // Issue #3 修复：旧 conclusion/detailsUrl 字段在 gh 中不存在。
+            const badge = formatCiBadge(c.state, c.bucket);
+            const url = c.link ? `[查看详情](${c.link})` : '-';
+            const wf = c.workflow ? sanitizeCell(c.workflow, 24) : '-';
+            return `| ${name} | ${badge} | ${wf} | ${url} |`;
+        });
+        return [
+            `**CI 检查结果 (${list.length} 项):**\n`,
+            '| 检查项名称 | 结论 / 状态 | 工作流 | 详情链接 |',
+            '| :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 1.3 PR Status (冲突与相关状态)
+    if (args?.action === 'status') {
+        const created = Array.isArray(value.createdBy) ? value.createdBy : [];
+        const review = Array.isArray(value.needsReview) ? value.needsReview : [];
+        const parts = ['### 🔀 当前分支关联 PR 状态\n'];
+        if (created.length > 0) {
+            parts.push('**由我发起的 PR:**\n| 编号 | 状态 | 冲突检测 | 标题 |', '| :--- | :--- | :--- | :--- |');
+            for (const p of created) {
+                const link = p.url ? `[#${p.number}](${p.url})` : `#${p.number}`;
+                parts.push(`| ${link} | ${formatStateBadge(p.state)} | ${formatConflictBadge(p.mergeStateStatus)} | ${sanitizeCell(p.title, 50)} |`);
+            }
+        }
+        else {
+            parts.push('当前分支未检测到本人发起的活跃 PR。');
+        }
+        if (review.length > 0) {
+            parts.push('\n**待我审查的 PR:**\n| 编号 | 状态 | 标题 |', '| :--- | :--- | :--- |');
+            for (const p of review) {
+                const link = p.url ? `[#${p.number}](${p.url})` : `#${p.number}`;
+                parts.push(`| ${link} | ${formatStateBadge(p.state)} | ${sanitizeCell(p.title, 50)} |`);
+            }
+        }
+        return parts.join('\n');
+    }
+    // 1.4 PR View 单卡详情
+    if (args?.action === 'view' && value.number) {
+        const link = value.url ? `[#${value.number}](${value.url})` : `#${value.number}`;
+        const badge = formatStateBadge(value.state, value.isDraft);
+        const author = value.author?.login ? `@${value.author.login}` : '-';
+        const lines = [
+            `### ${badge} ${value.title} (${link})`,
+            `- **作者**: ${author} | **分支**: \`${value.headRefName || '-'}\` → \`${value.baseRefName || 'main'}\``,
+            `- **合并判定**: ${formatConflictBadge(value.mergeable || value.mergeStateStatus)} | **审查判定**: ${value.reviewDecision || 'NONE'}`,
+        ];
+        if (Array.isArray(value.labels) && value.labels.length > 0) {
+            lines.push(`- **标签**: ${value.labels.map((l) => `\`${l.name || l}\``).join(' ')}`);
+        }
+        if (value.body) {
+            lines.push('\n**正文说明:**\n```markdown\n' + sanitizeCell(value.body, 300) + '\n```');
+        }
+        return lines.join('\n');
+    }
+    // 兜底降级
+    return JSON.stringify(value, null, 2);
+}

package/lib/renderers/project.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 渲染 GitHub OAuth Scope 权限缺失自愈引导卡片
+ */
+export declare function renderScopeRequiredMarkdown(value: any): string;
+/**
+ * 渲染 Projects 列表表格
+ */
+export declare function renderProjectList(items: any[]): string;
+/**
+ * 渲染单个 Project 详情卡片
+ */
+export declare function renderProjectView(p: any): string;
+/**
+ * 渲染 Project Items 看板条目列表
+ */
+export declare function renderProjectItemList(items: any[]): string;
+/**
+ * Project 领域综合渲染入口
+ */
+export declare function renderProjectMarkdown(args: any, value: any): string;

package/lib/renderers/project.js

@@ -0,0 +1,128 @@
+import { sanitizeCell } from './common.js';
+/**
+ * 渲染 GitHub OAuth Scope 权限缺失自愈引导卡片
+ */
+export function renderScopeRequiredMarkdown(value) {
+    const scope = value.scope || '相关权限';
+    const command = value.command || `gh auth refresh -s ${scope}`;
+    const toolName = value.tool ? `「${value.tool}」` : '';
+    return [
+        `> ### 🔑 需要补充 GitHub 权限授权 (Token Scope)`,
+        `> - **缺少权限**: \`${scope}\``,
+        `> - **影响工具**: ${toolName || '当前操作'}`,
+        `> - **自愈指引**: 请在宿主终端中执行以下单行命令完成授权：`,
+        `>   \`\`\`bash`,
+        `>   ${command}`,
+        `>   \`\`\``,
+        `> - **说明**: 授权完成后无需重启插件，直接重新调用当前工具即可正常执行。`,
+    ].join('\n');
+}
+/**
+ * 渲染 Projects 列表表格
+ */
+export function renderProjectList(items) {
+    const list = items.filter(Boolean);
+    if (list.length === 0) {
+        return '📭 暂无项目规划看板 (Projects)。';
+    }
+    const rows = list.map((p) => {
+        const num = p.number ? `#${p.number}` : '-';
+        const link = p.url ? `[${num}](${p.url})` : num;
+        const title = sanitizeCell(p.title || '(无标题)', 40);
+        const stateBadge = p.closed ? '🟣 CLOSED' : '🔵 OPEN';
+        const visibility = p.public ? '🌐 Public' : '🔒 Private';
+        const desc = sanitizeCell(p.shortDescription || p.readme || '-', 35);
+        return `| ${link} | ${title} | ${stateBadge} | ${visibility} | ${desc} |`;
+    });
+    return [
+        `**项目看板列表 (${list.length} 个):**\n`,
+        '| 编号 | 项目标题 | 状态 | 可见性 | 描述 |',
+        '| :--- | :--- | :--- | :--- | :--- |',
+        ...rows,
+    ].join('\n');
+}
+/**
+ * 渲染单个 Project 详情卡片
+ */
+export function renderProjectView(p) {
+    if (!p || typeof p !== 'object') {
+        return '无项目详情数据';
+    }
+    const num = p.number ? `#${p.number}` : '';
+    const title = p.title || '(无标题)';
+    const stateBadge = p.closed ? '🟣 CLOSED' : '🔵 OPEN';
+    const visibility = p.public ? '🌐 Public' : '🔒 Private';
+    const link = p.url ? `[打开项目网页](${p.url})` : '';
+    const lines = [
+        `### 📋 Project ${num}: ${title}\n`,
+        `- **状态**: ${stateBadge}`,
+        `- **可见性**: ${visibility}`,
+        `- **项目 ID**: \`${p.id || '-'}\``,
+    ];
+    if (link)
+        lines.push(`- **项目链接**: ${link}`);
+    if (p.shortDescription)
+        lines.push(`- **简述**: ${p.shortDescription}`);
+    if (p.readme) {
+        lines.push('\n**项目 README 说明:**', '---', p.readme.trim(), '---');
+    }
+    return lines.join('\n');
+}
+/**
+ * 渲染 Project Items 看板条目列表
+ */
+export function renderProjectItemList(items) {
+    const list = items.filter(Boolean);
+    if (list.length === 0) {
+        return '📭 当前项目看板中暂无任何条目 (Items)。';
+    }
+    const rows = list.map((item) => {
+        const rawId = String(item.id || '-');
+        const shortId = rawId.length > 8 ? `\`${rawId.slice(0, 8)}...\`` : `\`${rawId}\``;
+        const title = sanitizeCell(item.title || item.content?.title || '(无标题条目)', 45);
+        const type = item.type || (item.content?.type ? String(item.content.type) : 'DraftIssue');
+        const status = item.status || '-';
+        return `| ${shortId} | ${title} | \`${type}\` | ${status} |`;
+    });
+    return [
+        `**项目看板条目 (${list.length} 条):**\n`,
+        '| 条目 ID | 标题 / 内容 | 类型 | 状态看板 |',
+        '| :--- | :--- | :--- | :--- |',
+        ...rows,
+    ].join('\n');
+}
+/**
+ * Project 领域综合渲染入口
+ */
+export function renderProjectMarkdown(args, value) {
+    if (!value)
+        return '无返回内容';
+    if (value.status === 'SCOPE_REQUIRED') {
+        return renderScopeRequiredMarkdown(value);
+    }
+    if (value.status === 'AWAITING_CONFIRMATION') {
+        return [
+            `> ### ${value.warning || '⚠️ 操作确认拦截'}`,
+            `> - **影响评估**: ${value.impact || ''}`,
+            `> - **确认指引**: ${value.requiredAction || '如确认继续，请在参数中附加 `confirm: true` 重新调用。'}`,
+        ].join('\n');
+    }
+    if (typeof value.result === 'string')
+        return value.result;
+    if (typeof value.message === 'string' && !value.items && !value.projects) {
+        const extra = value.detail || value.output || value.url;
+        return `**${value.message}**` + (extra ? `\n\`\`\`\n${extra}\n\`\`\`` : '');
+    }
+    // 列表渲染（适配 projects 或 items 数组）
+    const listData = Array.isArray(value.projects) ? value.projects : (Array.isArray(value.items) ? value.items : null);
+    if (listData && args?.action === 'list') {
+        return renderProjectList(listData);
+    }
+    if (listData && args?.action === 'item-list') {
+        return renderProjectItemList(listData);
+    }
+    if (args?.action === 'view' || value.number) {
+        return renderProjectView(value);
+    }
+    return JSON.stringify(value, null, 2);
+}

package/lib/renderers/release.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Release 领域渲染器：负责版本发布历史列表与详情卡片（含资产清单、发布说明预览）
+ */
+export declare function renderReleaseMarkdown(args: any, value: any): string;

package/lib/renderers/release.js

@@ -0,0 +1,74 @@
+import { sanitizeCell, formatReleaseBadge } from './common.js';
+/**
+ * Release 领域渲染器：负责版本发布历史列表与详情卡片（含资产清单、发布说明预览）
+ */
+export function renderReleaseMarkdown(args, value) {
+    if (!value)
+        return '无返回内容';
+    if (value.status === 'AWAITING_CONFIRMATION') {
+        return [
+            `> ### ${value.warning || '⚠️ 高危操作拦截警告'}`,
+            `> - **影响评估**: ${value.impact || '该操作将改变远端仓库状态。'}`,
+            `> - **确认指引**: ${value.requiredAction || '如确认继续，请向用户核实并在参数中附加 `confirm: true` 重新调用。'}`,
+        ].join('\n');
+    }
+    if (typeof value.result === 'string')
+        return value.result;
+    if (typeof value.message === 'string' && !value.items) {
+        const extra = value.detail || value.output;
+        return `**${value.message}**` + (value.url ? `\n🔗 链接: ${value.url}` : '') + (extra ? `\n\`\`\`\n${extra}\n\`\`\`` : '');
+    }
+    // 5.1 Release 列表
+    if (Array.isArray(value.items) && args?.action === 'list') {
+        const list = value.items.filter(Boolean);
+        if (list.length === 0)
+            return '📭 当前仓库暂无任何 Release。';
+        const rows = list.map((r) => {
+            const tag = r.tagName ? `\`${r.tagName}\`` : '-';
+            const name = sanitizeCell(r.name || r.tagName, 40);
+            const badge = formatReleaseBadge(r.isDraft, r.isPrerelease);
+            const date = (r.publishedAt || r.createdAt || '').slice(0, 10) || '-';
+            return `| ${tag} | ${badge} | ${name} | ${date} |`;
+        });
+        return [
+            `**最近 ${list.length} 个 Release:**\n`,
+            '| Tag | 类型 | 名称 | 发布日期 |',
+            '| :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 5.2 Release 详情卡片
+    if (args?.action === 'view' && value.tagName) {
+        const badge = formatReleaseBadge(value.isDraft, value.isPrerelease);
+        const lines = [
+            `### 🏷️ Release \`${value.tagName}\` ${badge}`,
+        ];
+        // 元信息压缩成一段（硬换行分隔），避免逐行 filter 空串把段落分隔也滤掉。
+        // Markdown 的列表/段落渲染依赖空行：若标题、资产列表、正文之间没有空行，
+        // 列表语法会失效并连成一段——所以这里改为「分段数组 + 空行 join」。
+        const meta = [];
+        if (value.name)
+            meta.push(`**${value.name}**`);
+        if (value.url)
+            meta.push(`🔗 ${value.url}`);
+        if (value.publishedAt)
+            meta.push(`📅 发布于 ${value.publishedAt.slice(0, 10)}`);
+        if (meta.length > 0)
+            lines.push(meta.join('  \n'));
+        if (Array.isArray(value.assets) && value.assets.length > 0) {
+            const assetLines = value.assets.map((a) => {
+                const size = typeof a.size === 'number' ? ` (${(a.size / 1024).toFixed(1)} KB)` : '';
+                return `- \`${a.name || '-'}\`${size}`;
+            });
+            lines.push(`**📎 附属资产 (${value.assets.length}):**\n${assetLines.join('\n')}`);
+        }
+        if (value.body) {
+            // 发版说明可能非常长，只保留前 600 字符做快速预览，避免单次调用撑爆上下文
+            const preview = value.body.length > 600 ? value.body.slice(0, 600) + '\n…(已截断，完整内容见 Release 页面)' : value.body;
+            lines.push(`**📝 发版说明摘要:**\n\n${preview}`);
+        }
+        return lines.join('\n\n');
+    }
+    // 兜底降级
+    return JSON.stringify(value, null, 2);
+}

package/lib/renderers/repo.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Repo 领域渲染器：负责仓库卡片概览、README 预览、代码/仓库/Issue/Commit 跨仓检索、免 Clone 文件与目录清单渲染
+ */
+export declare function renderRepoMarkdown(args: any, value: any): string;

package/lib/renderers/repo.js

@@ -0,0 +1,149 @@
+import { sanitizeCell, formatStateBadge, appendDegradedNote } from './common.js';
+/**
+ * Repo 领域渲染器：负责仓库卡片概览、README 预览、代码/仓库/Issue/Commit 跨仓检索、免 Clone 文件与目录清单渲染
+ */
+export function renderRepoMarkdown(args, value) {
+    if (!value)
+        return '无返回内容';
+    if (typeof value.result === 'string')
+        return value.result;
+    // 4.0 README 预览（文本截断版 + 图片清单）——必须在 message 早退分支之前：
+    // readme 返回同时带 message 与 readme 字段，先判 readme 才能渲染预览而非一行摘要
+    if (args?.action === 'readme' && typeof value.readme === 'string') {
+        const lines = [`### 📖 README 预览`, '', '```markdown', value.readme, '```'];
+        if (Array.isArray(value.images) && value.images.length > 0) {
+            lines.push('', `**📎 图片清单 (${value.images.length}):** 可用 \`image_urls\` 参数下载指定图片（留空下载全部）`);
+            value.images.slice(0, 8).forEach((u, i) => lines.push(`${i + 1}. ${u}`));
+            if (value.images.length > 8)
+                lines.push(`…共 ${value.images.length} 个`);
+        }
+        return lines.join('\n');
+    }
+    if (typeof value.message === 'string' && !value.items) {
+        return `**${value.message}**` + (value.output ? `\n\`\`\`\n${value.output}\n\`\`\`` : '');
+    }
+    // 4.1 Repo View 概览卡片
+    if (args?.action === 'view' && value.nameWithOwner) {
+        const link = value.url ? `[${value.nameWithOwner}](${value.url})` : `**${value.nameWithOwner}**`;
+        const stars = value.stargazerCount ?? value.stars ?? 0;
+        const forks = value.forkCount ?? value.forks ?? 0;
+        const branch = value.defaultBranchRef?.name || value.defaultBranch || 'main';
+        const lines = [
+            `### 📦 ${link}`,
+            `> ⭐ **Stars**: ${stars} | 🍴 **Forks**: ${forks} | ⎇ **默认分支**: \`${branch}\``,
+            value.description ? `\n${value.description}\n` : '',
+        ];
+        if (value.licenseInfo?.name || value.licenseInfo?.key) {
+            lines.push(`- **开源协议**: \`${value.licenseInfo.name || value.licenseInfo.key}\``);
+        }
+        if (Array.isArray(value.repositoryTopics) && value.repositoryTopics.length > 0) {
+            lines.push(`- **仓库标签 (Topics)**: ${value.repositoryTopics.map((t) => `\`${t.name || t}\``).join(' ')}`);
+        }
+        return lines.filter(Boolean).join('\n');
+    }
+    // 4.2 Repo Search 仓库搜索列表
+    if (Array.isArray(value.items) && args?.action === 'search_repos') {
+        if (value.items.length === 0)
+            return '未找到匹配的仓库。';
+        const rows = value.items.map((r) => {
+            const name = r.fullName ? `[${r.fullName}](https://github.com/${r.fullName})` : '-';
+            const stars = r.stargazersCount ?? '-';
+            const desc = sanitizeCell(r.description, 45);
+            const date = r.updatedAt ? r.updatedAt.slice(0, 10) : '-';
+            return `| ${name} | ⭐ ${stars} | ${desc} | ${date} |`;
+        });
+        return [
+            `**仓库检索结果 (${value.items.length} 个):**\n`,
+            '| 仓库全名 | Stars | 描述 | 更新日期 |',
+            '| :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 4.3 Code Search 代码搜索列表
+    if (Array.isArray(value.items) && args?.action === 'search_code') {
+        if (value.items.length === 0)
+            return '未找到匹配的代码片段。';
+        const rows = value.items.map((c) => {
+            const repo = c.repository?.fullName || '-';
+            const path = sanitizeCell(c.path, 50);
+            return `| \`${path}\` | ${repo} |`;
+        });
+        return [
+            `**代码检索结果 (${value.items.length} 处匹配):**\n`,
+            '| 文件路径 | 所属仓库 |',
+            '| :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 4.4 Issue/PR 搜索列表（search_issues / search_prs 共用，字段同构）
+    if (Array.isArray(value.items) && (args?.action === 'search_issues' || args?.action === 'search_prs')) {
+        if (value.items.length === 0)
+            return '未找到匹配的结果。';
+        const kind = args.action === 'search_prs' ? 'PR' : 'Issue';
+        const rows = value.items.map((it) => {
+            const num = it.number ?? '-';
+            const repo = it.repository?.nameWithOwner || it.repository?.fullName || '-';
+            const link = it.url ? `[#${num}](${it.url})` : `#${num}`;
+            const badge = formatStateBadge(it.state, it.isDraft);
+            const author = it.author?.login || '-';
+            const date = it.updatedAt ? String(it.updatedAt).slice(0, 10) : '-';
+            return `| ${link} | ${sanitizeCell(it.title, 45)} | ${badge} | ${repo} | ${author} | ${date} |`;
+        });
+        return [
+            `**${kind} 检索结果 (${value.items.length} 条):**\n`,
+            '| 编号 | 标题 | 状态 | 仓库 | 作者 | 更新日期 |',
+            '| :--- | :--- | :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 4.5 Commit 搜索列表（嵌套 commit.commit.message 取首行）
+    if (Array.isArray(value.items) && args?.action === 'search_commits') {
+        if (value.items.length === 0)
+            return '未找到匹配的提交。';
+        const rows = value.items.map((c) => {
+            const sha = `\`${String(c.sha || '').slice(0, 7)}\``;
+            const msg = sanitizeCell(String(c.commit?.message || '').split('\n')[0], 50);
+            const author = c.commit?.author?.name || c.author?.login || '-';
+            const repo = c.repository?.fullName || '-';
+            return `| ${sha} | ${msg} | ${author} | ${repo} |`;
+        });
+        return [
+            `**提交检索结果 (${value.items.length} 条):**\n`,
+            '| SHA | 提交信息 | 作者 | 仓库 |',
+            '| :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 4.6 目录清单（read_dir：dir 置顶 + size 人性化；mode 八进制是 Git 内部语义不展示）
+    if (args?.action === 'read_dir' && Array.isArray(value.items)) {
+        if (value.items.length === 0)
+            return `**${value.path || '/'}** 为空目录。` + appendDegradedNote(value);
+        const sorted = [...value.items].sort((a, b) => (a.type === b.type ? String(a.name).localeCompare(String(b.name)) : a.type === 'dir' ? -1 : 1));
+        const rows = sorted.map((e) => {
+            const icon = e.type === 'dir' ? '📁' : '📄';
+            const size = e.type === 'dir' ? '-' : (typeof e.size === 'number' ? (e.size > 1024 ? `${(e.size / 1024).toFixed(1)}KB` : `${e.size}B`) : '-');
+            return `| ${icon} \`${sanitizeCell(e.name, 60)}\` | ${size} |`;
+        });
+        return [
+            `**目录 ${value.path || '/'}（${value.items.length} 项）:**\n`,
+            '| 名称 | 大小 |',
+            '| :--- | :--- |',
+            ...rows,
+            appendDegradedNote(value),
+        ].filter((l) => l !== '').join('\n');
+    }
+    // 4.7 文件内容（read_file：代码块 + 元信息行）
+    if (args?.action === 'read_file' && typeof value.content === 'string') {
+        const ext = (value.path || '').split('.').pop() || '';
+        const size = typeof value.size === 'number' ? (value.size > 1024 ? `${(value.size / 1024).toFixed(1)}KB` : `${value.size}B`) : '-';
+        return [
+            `**📄 \`${value.path}\`** (${size}${value.ref ? ` @ ${value.ref}` : ''})\n`,
+            '```' + ext,
+            value.content,
+            '```',
+            appendDegradedNote(value),
+        ].filter((l) => l !== '').join('\n');
+    }
+    // 兜底降级
+    return JSON.stringify(value, null, 2);
+}

package/lib/renderers/ruleset.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Ruleset 领域渲染器：负责 GitHub Rulesets 列表、详情与分支策略 check 的 Markdown 格式化
+ */
+export declare function renderRulesetMarkdown(args: any, value: any): string;

package/lib/renderers/ruleset.js

@@ -0,0 +1,74 @@
+import { sanitizeCell } from './common.js';
+/**
+ * Ruleset 领域渲染器：负责 GitHub Rulesets 列表、详情与分支策略 check 的 Markdown 格式化
+ */
+export function renderRulesetMarkdown(args, value) {
+    if (!value)
+        return '无返回内容';
+    if (typeof value.result === 'string')
+        return value.result;
+    // 1. check 操作格式化展示（策略视角 PR 无法合并的核心排障答案）
+    if (args?.action === 'check') {
+        const branch = value.branch || args?.branch || '当前分支';
+        const repo = value.repo || args?.repo || '-';
+        const ruleCount = typeof value.ruleCount === 'number' ? value.ruleCount : 0;
+        if (ruleCount === 0) {
+            return [
+                `🟢 分支 \`${branch}\`（仓库 \`${repo}\`）当前**未受任何 Ruleset 规则保护或策略限制**。`,
+                '',
+                '> 💡 **PR 合并排障指南**: 该分支无策略规则阻断。若 PR 依然无法合并，通常是因为：',
+                '> 1. **CI 未通过**: 请调用 \\`github_pr(action: \'checks\')\\` 审查 CI 检查项，若有失败调用 \\`github_run(action: \'log_failed\')\\`；',
+                '> 2. **代码冲突**: 请检查 PR 的 \\`mergeable\\` 状态；',
+                '> 3. **Draft 状态**: 若为草稿，请使用 \\`github_pr(action: \'ready\')\\` 转为可评审状态。',
+            ].join('\n');
+        }
+        const items = Array.isArray(value.rules) ? value.rules : [];
+        const ruleRows = items.map((r) => {
+            const name = r.name ? `🔒 **${r.name}**` : '-';
+            const params = r.params ? `\`${sanitizeCell(r.params, 50)}\`` : '-';
+            const source = r.source ? sanitizeCell(r.source, 40) : '-';
+            return `| ${name} | ${params} | ${source} |`;
+        });
+        const tablePart = items.length > 0
+            ? [
+                '| 规则类型 | 约束详情 | 规则集来源 |',
+                '| :--- | :--- | :--- |',
+                ...ruleRows,
+            ].join('\n')
+            : (value.rawText ? `\`\`\`\n${value.rawText}\n\`\`\`` : '');
+        return [
+            `⚠️ 分支 \`${branch}\`（仓库 \`${repo}\`）受到 **${ruleCount}** 项策略规则保护与约束:\n`,
+            tablePart,
+            '',
+            '> 💡 **PR 合并策略排障**: PR 合并必须满足上述硬性规则（如必审批准人数、指定 CI 门禁、线性历史、签名提交等）。与 \\`github_pr(action: \'checks\')\\` 配合可完整诊断“PR 为何无法合并”。',
+        ].join('\n');
+    }
+    // 2. list 操作格式化展示
+    if (args?.action === 'list') {
+        const raw = (value.rawText || value.output || '').trim();
+        if (!raw) {
+            return '📭 目标仓库/组织当前未配置任何规则集 (Rulesets)。';
+        }
+        return [
+            `**规则集列表 (Rulesets):**\n`,
+            '```',
+            raw,
+            '```',
+        ].join('\n');
+    }
+    // 3. view 操作格式化展示
+    if (args?.action === 'view') {
+        const raw = (value.rawText || value.output || '').trim();
+        const idHint = value.ruleset_id ? ` (ID: ${value.ruleset_id})` : '';
+        return [
+            `### 🛡️ 规则集详情${idHint}\n`,
+            '```',
+            raw || '无详细规则内容',
+            '```',
+        ].join('\n');
+    }
+    // 4. 兜底
+    if (typeof value.message === 'string')
+        return value.message;
+    return JSON.stringify(value, null, 2);
+}

package/lib/renderers/run.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Actions Run 领域渲染器：负责工作流运行列表、工作流清单、工作流详情与单次 Run 状态渲染
+ */
+export declare function renderRunMarkdown(args: any, value: any): string;

package/lib/renderers/run.js

@@ -0,0 +1,79 @@
+import { sanitizeCell, formatCiBadge } from './common.js';
+/**
+ * Actions Run 领域渲染器：负责工作流运行列表、工作流清单、工作流详情与单次 Run 状态渲染
+ */
+export function renderRunMarkdown(args, value) {
+    if (!value)
+        return '无返回数据';
+    if (typeof value.result === 'string')
+        return value.result;
+    if (typeof value.message === 'string' && !value.items) {
+        return `**${value.message}**` + (value.output ? `\n\`\`\`\n${value.output}\n\`\`\`` : '');
+    }
+    // 3.1 Run 列表
+    if (Array.isArray(value.items) && args?.action === 'list') {
+        const list = value.items.filter(Boolean);
+        if (list.length === 0)
+            return '📭 暂无匹配的工作流运行记录。';
+        const rows = list.map((r) => {
+            const idLink = r.url ? `[${r.databaseId}](${r.url})` : `\`${r.databaseId}\``;
+            const badge = formatCiBadge(r.status, r.conclusion);
+            const name = sanitizeCell(r.name, 35);
+            const branch = r.headBranch ? `\`${r.headBranch}\`` : '-';
+            const event = r.event || '-';
+            const time = r.createdAt ? r.createdAt.slice(0, 16).replace('T', ' ') : '-';
+            return `| ${idLink} | ${badge} | ${name} | ${branch} | ${event} | ${time} |`;
+        });
+        return [
+            `**最近 ${list.length} 次工作流运行:**\n`,
+            '| Run ID | 结论 / 状态 | 工作流名称 | 触发分支 | 触发事件 | 运行时间 |',
+            '| :--- | :--- | :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 3.2 Workflow 清单（字段集为 gh 2.96 实测合法全集 4 个）
+    if (Array.isArray(value.items) && args?.action === 'workflow_list') {
+        const list = value.items.filter(Boolean);
+        if (list.length === 0)
+            return args?.all === true ? '📭 该仓库没有任何工作流。' : '📭 暂无 active 工作流（可能全部 disabled，传 all: true 查看）。';
+        const rows = list.map((w) => {
+            const badge = w.state === 'active' ? '🟢 active' : (w.state === 'disabled' ? '🔴 disabled' : String(w.state || '-'));
+            return `| \`${w.id}\` | ${sanitizeCell(w.name, 40)} | ${badge} | \`${sanitizeCell(w.path, 45)}\` |`;
+        });
+        return [
+            `**工作流清单 (${list.length} 个${args?.all === true ? '，含 disabled' : ''}):**\n`,
+            '| ID | 名称 | 状态 | 文件 |',
+            '| :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 3.3 Workflow 详情（gh 无 --json，头部结构化 + Recent runs 原文引用块——D4 决策）
+    if (args?.action === 'workflow_view' && value.workflow) {
+        const lines = [
+            `### 🔄 ${value.workflow}`,
+            `- **ID**: \`${value.id || '-'}\`${value.totalRuns ? ` | **累计运行**: ${value.totalRuns} 次` : ''}`,
+        ];
+        if (value.recentRuns) {
+            lines.push('', '**最近运行:**', '```', value.recentRuns, '```');
+        }
+        return lines.join('\n');
+    }
+    // 3.4 Run View 详情
+    if (args?.action === 'view' && value.databaseId) {
+        const idLink = value.url ? `[${value.databaseId}](${value.url})` : `\`${value.databaseId}\``;
+        const badge = formatCiBadge(value.status, value.conclusion);
+        const lines = [
+            `### 工作流: ${value.name} (Run: ${idLink})`,
+            `- **状态**: ${badge}`,
+        ];
+        if (Array.isArray(value.jobs) && value.jobs.length > 0) {
+            lines.push('\n**Jobs 步骤明细:**\n| Job 名称 | 结论 / 状态 | 详情 |', '| :--- | :--- | :--- |');
+            for (const j of value.jobs) {
+                lines.push(`| ${sanitizeCell(j.name, 30)} | ${formatCiBadge(j.status, j.conclusion)} | ${j.url ? `[链接](${j.url})` : '-'} |`);
+            }
+        }
+        return lines.join('\n');
+    }
+    // 兜底降级
+    return JSON.stringify(value, null, 2);
+}