dsh-github-flow 0.3.0 → 0.4.0

package/lib/git-watcher.js

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * 定向针对 .git/HEAD 与 .git/index 创建非递归文件系统监听器。
+ * 零源码目录遍历，避免句柄耗尽与高 CPU 占用。
+ *
+ * 核心机制：
+ * 1. 靶向监听：仅监控 .git/HEAD 与 .git/index，若都不存在则兜底监控 .git 目录；
+ * 2. 800ms 防抖合并：避免连续 git 操作（如 git add 多个文件）产生事件风暴；
+ * 3. 单次触发保证（At-Most-Once）：变更触发或超时熔断后，立即自动执行清理并释放全部句柄；
+ * 4. 显式释放：返回可随时主动调用的清理函数 stop()。
+ *
+ * @param cwd 目标 Git 仓库根目录
+ * @param onTrigger 变更发生或超时触发时的回调函数
+ * @param options 可选配置项（防抖与超时时间）
+ * @returns 停止监听并释放全部句柄的清理函数
+ */
+export function watchGitMetadata(cwd, onTrigger, options) {
+    const debounceMs = options?.debounceMs ?? 800;
+    const timeoutMs = options?.timeoutMs ?? 35_000;
+    const gitDir = path.join(cwd, '.git');
+    let stopped = false;
+    let debounceTimer = null;
+    let timeoutTimer = null;
+    const watchers = [];
+    const cleanup = () => {
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+            debounceTimer = null;
+        }
+        if (timeoutTimer) {
+            clearTimeout(timeoutTimer);
+            timeoutTimer = null;
+        }
+        for (const w of watchers) {
+            try {
+                w.close();
+            }
+            catch { }
+        }
+        watchers.length = 0;
+    };
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        cleanup();
+    };
+    const triggerChange = () => {
+        if (stopped)
+            return;
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            if (stopped)
+                return;
+            stopped = true;
+            cleanup();
+            try {
+                onTrigger({ changed: true, at: Date.now() });
+            }
+            catch { }
+        }, debounceMs);
+    };
+    try {
+        const targets = [path.join(gitDir, 'HEAD'), path.join(gitDir, 'index')];
+        for (const target of targets) {
+            if (fs.existsSync(target)) {
+                watchers.push(fs.watch(target, triggerChange));
+            }
+        }
+        if (watchers.length === 0 && fs.existsSync(gitDir)) {
+            watchers.push(fs.watch(gitDir, triggerChange));
+        }
+        timeoutTimer = setTimeout(() => {
+            if (stopped)
+                return;
+            stopped = true;
+            cleanup();
+            try {
+                onTrigger({ timeout: true });
+            }
+            catch { }
+        }, timeoutMs);
+    }
+    catch (err) {
+        cleanup();
+        throw err;
+    }
+    return stop;
+}

package/lib/main.js

@@ -7,6 +7,11 @@ import { createApiTool } from './tools/api.js';
 import { createReleaseTool } from './tools/release.js';
 import { createSecretTool } from './tools/secret.js';
 import { createSkillTool } from './tools/skill.js';
+import { createLabelTool } from './tools/label.js';
+import { createRulesetTool } from './tools/ruleset.js';
+import { createCacheTool } from './tools/cache.js';
+import { createGistTool } from './tools/gist.js';
+import { createStatusTool } from './tools/status.js';
 import { createHelpTool } from './tools/help.js';
 import { registerGhCommand } from './commands/gh.js';
 import { registerApiRoutes } from './api/routes.js';
@@ -97,6 +102,11 @@ export function apply(ctx, config = {}) {
         ctx.tools.register(createReleaseTool(executor));
         ctx.tools.register(createSecretTool(executor));
         ctx.tools.register(createSkillTool(executor));
+        ctx.tools.register(createLabelTool(executor));
+        ctx.tools.register(createRulesetTool(executor));
+        ctx.tools.register(createCacheTool(executor));
+        ctx.tools.register(createGistTool(executor));
+        ctx.tools.register(createStatusTool(executor));
         ctx.tools.register(createHelpTool(executor));
     }
     // 4. 注册面向 Client 端的 WebServer HTTP 路由（如果当前环境启用了 Web UI 服务）

package/lib/renderers/cache.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 友好文件大小换算：B -> KB -> MB -> GB
+ */
+export declare function formatBytes(bytes?: number): string;
+/**
+ * Cache 领域渲染器：负责 GitHub Actions 缓存列表、容量盘点与清理操作的 Markdown 格式化
+ */
+export declare function renderCacheMarkdown(args: any, value: any): string;

package/lib/renderers/cache.js

@@ -0,0 +1,66 @@
+import { sanitizeCell } from './common.js';
+/**
+ * 友好文件大小换算：B -> KB -> MB -> GB
+ */
+export function formatBytes(bytes) {
+    if (typeof bytes !== 'number' || isNaN(bytes) || bytes <= 0)
+        return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.min(Math.floor(Math.log(bytes) / Math.log(k)), sizes.length - 1);
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
+/**
+ * Cache 领域渲染器：负责 GitHub Actions 缓存列表、容量盘点与清理操作的 Markdown 格式化
+ */
+export function renderCacheMarkdown(args, value) {
+    if (!value)
+        return '无返回内容';
+    // 1. 高危操作确认拦截报告
+    if (value.status === 'AWAITING_CONFIRMATION') {
+        return [
+            `> ### ${value.warning || '⚠️ 操作确认拦截'}`,
+            `> - **影响评估**: ${value.impact || ''}`,
+            `> - **确认指引**: ${value.requiredAction || '如确认继续，请在参数中附加 \\`confirm: true\\` 重新调用。'}`,
+        ].join('\n');
+    }
+    if (typeof value.result === 'string')
+        return value.result;
+    // 2. 单操作消息提示（delete 等）
+    if (typeof value.message === 'string' && !value.items) {
+        const extra = value.detail || value.output;
+        return `**${value.message}**` + (extra ? `\n\`\`\`\n${extra}\n\`\`\`` : '');
+    }
+    // 3. 缓存列表展示
+    if (Array.isArray(value.items)) {
+        const list = value.items.filter(Boolean);
+        if (list.length === 0) {
+            return args?.key
+                ? `📭 未检索到匹配键名 "${args.key}" 的 Actions 缓存。`
+                : '📭 仓库中当前未发现任何 Actions 缓存。';
+        }
+        let totalBytes = 0;
+        const rows = list.map((item) => {
+            const id = item.id ? `\`${item.id}\`` : '-';
+            const key = item.key ? `\`${sanitizeCell(item.key, 35)}\`` : '-';
+            const sizeNum = typeof item.sizeInBytes === 'number' ? item.sizeInBytes : 0;
+            totalBytes += sizeNum;
+            const sizeStr = formatBytes(sizeNum);
+            const ref = item.ref ? `\`${sanitizeCell(item.ref, 25)}\`` : '-';
+            const lastAccess = item.lastAccessedAt ? item.lastAccessedAt.replace('T', ' ').replace('Z', '') : '-';
+            return `| ${id} | ${key} | ${sizeStr} | ${ref} | ${lastAccess} |`;
+        });
+        const keyHint = args?.key ? ` (过滤键: "${args.key}")` : '';
+        const totalSizeStr = formatBytes(totalBytes);
+        return [
+            `**Actions 缓存列表 (${list.length} 个, 总计占用 ${totalSizeStr})${keyHint}:**\n`,
+            '| 缓存 ID | 键名 (Key) | 大小 | 关联 Ref | 最后访问时间 |',
+            '| :--- | :--- | :--- | :--- | :--- |',
+            ...rows,
+            '',
+            '> 💡 **缓存治理建议**: 若 Actions 构建耗时变长或缓存过载，可使用 `github_cache(action: \'delete\', cache_id: ...)` 精准清理，或通过 `all: true, confirm: true` 全量清空。',
+        ].join('\n');
+    }
+    // 4. 兜底降级
+    return JSON.stringify(value, null, 2);
+}

package/lib/renderers/common.d.ts

@@ -0,0 +1,24 @@
+/**
+ * DSH GitHub Flow - 通用 Markdown 格式化原子工具与状态徽章
+ */
+/** 安全清洗表格单元格文本：转义竖线，压缩换行，限制最大长度 */
+export declare function sanitizeCell(text: any, maxLen?: number): string;
+/** 格式化 PR / Issue 状态药丸徽章 */
+export declare function formatStateBadge(state?: string, isDraft?: boolean): string;
+/**
+ * 格式化 CI 工作流状态徽章。
+ * 第二参数按调用域语义不同：run 域传 conclusion（success/failure/cancelled/skipped），
+ * pr checks 域传 bucket（pass/fail/pending/skipping/cancel）——取值族不同但映射到
+ * 同一组徽章；state 参数兜底（in_progress/queued 等进行中态）。
+ */
+export declare function formatCiBadge(status?: string, conclusion?: string): string;
+/** 格式化合并冲突状态 */
+export declare function formatConflictBadge(status?: string): string;
+/** 格式化 Release 状态徽章 */
+export declare function formatReleaseBadge(isDraft?: boolean, isPrerelease?: boolean): string;
+/**
+ * 降级链路可见标注（runGuarded 契约的渲染兑现）。
+ * 为什么必须可见：降级若是静默的，Agent 就无法感知能力边界（同一 action 在
+ * 不同 gh 版本上走不同链路）；一条 blockquote 注释成本一行，换链路透明。
+ */
+export declare function appendDegradedNote(value: any): string;

package/lib/renderers/common.js

@@ -0,0 +1,88 @@
+/**
+ * DSH GitHub Flow - 通用 Markdown 格式化原子工具与状态徽章
+ */
+/** 安全清洗表格单元格文本：转义竖线，压缩换行，限制最大长度 */
+export function sanitizeCell(text, maxLen = 80) {
+    if (text === null || text === undefined || text === '')
+        return '-';
+    const clean = String(text)
+        .replace(/\|/g, '\\|')
+        .replace(/[\r\n]+/g, ' ')
+        .trim();
+    if (clean.length > maxLen) {
+        return clean.slice(0, maxLen - 1) + '…';
+    }
+    return clean || '-';
+}
+/** 格式化 PR / Issue 状态药丸徽章 */
+export function formatStateBadge(state, isDraft) {
+    if (!state)
+        return '-';
+    const s = state.toUpperCase();
+    if (isDraft)
+        return '⚪ DRAFT';
+    if (s === 'OPEN')
+        return '🟢 OPEN';
+    if (s === 'MERGED')
+        return '🟣 MERGED';
+    if (s === 'CLOSED')
+        return '🔴 CLOSED';
+    return s;
+}
+/**
+ * 格式化 CI 工作流状态徽章。
+ * 第二参数按调用域语义不同：run 域传 conclusion（success/failure/cancelled/skipped），
+ * pr checks 域传 bucket（pass/fail/pending/skipping/cancel）——取值族不同但映射到
+ * 同一组徽章；state 参数兜底（in_progress/queued 等进行中态）。
+ */
+export function formatCiBadge(status, conclusion) {
+    const conc = (conclusion || '').toLowerCase();
+    const st = (status || '').toLowerCase();
+    if (conc === 'success' || conc === 'pass')
+        return '✅ ' + conc;
+    if (conc === 'failure' || conc === 'fail')
+        return '❌ ' + conc;
+    if (conc === 'cancelled' || conc === 'cancel')
+        return '🚫 ' + conc;
+    if (conc === 'skipped' || conc === 'skipping')
+        return '⏭️ ' + conc;
+    if (conc === 'pending')
+        return '⏳ pending';
+    if (st === 'in_progress')
+        return '⏳ running';
+    if (st === 'queued')
+        return '⏱️ queued';
+    return conc || st || '-';
+}
+/** 格式化合并冲突状态 */
+export function formatConflictBadge(status) {
+    if (!status)
+        return '-';
+    const s = status.toUpperCase();
+    if (s === 'CLEAN')
+        return '✅ CLEAN';
+    if (s === 'DIRTY' || s === 'CONFLICT')
+        return '⚠️ CONFLICT';
+    if (s === 'BLOCKED')
+        return '⛔ BLOCKED';
+    return s;
+}
+/** 格式化 Release 状态徽章 */
+export function formatReleaseBadge(isDraft, isPrerelease) {
+    if (isDraft)
+        return '⚪ DRAFT';
+    if (isPrerelease)
+        return '🍼 PRE';
+    return '✅ STABLE';
+}
+/**
+ * 降级链路可见标注（runGuarded 契约的渲染兑现）。
+ * 为什么必须可见：降级若是静默的，Agent 就无法感知能力边界（同一 action 在
+ * 不同 gh 版本上走不同链路）；一条 blockquote 注释成本一行，换链路透明。
+ */
+export function appendDegradedNote(value) {
+    if (value && value.degraded === true && value.degradedReason) {
+        return `\n\n> ⚠️ ${value.degradedReason}`;
+    }
+    return '';
+}

package/lib/renderers/gist.d.ts

@@ -0,0 +1,15 @@
+export interface ParsedGistSummary {
+    id: string;
+    description: string;
+    filesCount: string;
+    visibility: string;
+    updatedAt: string;
+}
+/**
+ * 解析 gh gist list 的制表符/多列纯文本输出
+ */
+export declare function parseGistListOutput(output: string): ParsedGistSummary[];
+/**
+ * Gist 领域渲染器：负责 GitHub Gist 列表、代码正文、创建/删除反馈的 Markdown 格式化
+ */
+export declare function renderGistMarkdown(args: any, value: any): string;

package/lib/renderers/gist.js

@@ -0,0 +1,99 @@
+import { sanitizeCell } from './common.js';
+/**
+ * 解析 gh gist list 的制表符/多列纯文本输出
+ */
+export function parseGistListOutput(output) {
+    const trimmed = (output || '').trim();
+    if (!trimmed)
+        return [];
+    const lines = trimmed.split(/[\r\n]+/).map((l) => l.trim()).filter(Boolean);
+    const results = [];
+    for (const line of lines) {
+        let parts = line.split('\t');
+        if (parts.length < 2) {
+            parts = line.split(/\s{2,}/);
+        }
+        if (parts.length >= 1 && parts[0].length >= 8) {
+            results.push({
+                id: parts[0].trim(),
+                description: (parts[1] || '').trim(),
+                filesCount: (parts[2] || '').trim(),
+                visibility: (parts[3] || 'secret').trim(),
+                updatedAt: (parts[4] || '').trim(),
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Gist 领域渲染器：负责 GitHub Gist 列表、代码正文、创建/删除反馈的 Markdown 格式化
+ */
+export function renderGistMarkdown(args, value) {
+    if (!value)
+        return '无返回内容';
+    // 1. 高危操作确认拦截报告
+    if (value.status === 'AWAITING_CONFIRMATION') {
+        return [
+            `> ### ${value.warning || '⚠️ 操作确认拦截'}`,
+            `> - **影响评估**: ${value.impact || ''}`,
+            `> - **确认指引**: ${value.requiredAction || '如确认继续，请在参数中附加 \\`confirm: true\\` 重新调用。'}`,
+        ].join('\n');
+    }
+    if (typeof value.result === 'string')
+        return value.result;
+    // 2. create 操作卡片展示
+    if (args?.action === 'create' && value.url) {
+        const visBadge = value.public ? '🌐 Public' : '🔒 Secret (Unlisted)';
+        const descHint = value.description ? `\n> - **描述**: ${value.description}` : '';
+        return [
+            `✅ **成功创建 Gist 代码片段**:\n`,
+            `- **访问链接**: [${value.url}](${value.url})`,
+            `- **Gist ID**: \`${value.gist_id}\``,
+            `- **可见性**: ${visBadge}${descHint}`,
+            '',
+            '> ⚠️ **安全须知**: Secret Gist 属于未列出（Unlisted）公开可寻址资源，拥有链接的任何人均可访问，切勿存放私有凭证或敏感机密。',
+        ].join('\n');
+    }
+    // 3. view 操作展示
+    if (args?.action === 'view') {
+        const raw = (value.content || value.rawText || '').trim();
+        const id = value.gist_id || args?.gist_id || '';
+        const fileHint = args?.filename ? ` (${args.filename})` : '';
+        return [
+            `### 📄 Gist 代码片段: \`${id}\`${fileHint}\n`,
+            '```',
+            raw || '无代码内容',
+            '```',
+        ].join('\n');
+    }
+    // 4. list 操作表格展示
+    if (args?.action === 'list') {
+        const list = Array.isArray(value.items) ? value.items : [];
+        if (list.length === 0) {
+            return '📭 当前 GitHub 账号下尚未创建任何 Gist 代码片段。';
+        }
+        const rows = list.map((g) => {
+            const id = g.id ? `\`${g.id}\`` : '-';
+            const desc = sanitizeCell(g.description, 35);
+            const files = g.filesCount ? `\`${g.filesCount}\`` : '-';
+            const vis = g.visibility === 'public' ? '🌐 public' : '🔒 secret';
+            const updated = sanitizeCell(g.updatedAt, 20);
+            return `| ${id} | ${desc} | ${files} | ${vis} | ${updated} |`;
+        });
+        return [
+            `**Gist 代码片段列表 (${list.length} 个):**\n`,
+            '| Gist ID | 描述 / 摘要 | 文件数 | 可见性 | 最近更新 |',
+            '| :--- | :--- | :--- | :--- | :--- |',
+            ...rows,
+            '',
+            '> 💡 **查看指南**: 调用 `github_gist(action: \'view\', gist_id: \'...\')` 可查看完整代码正文。',
+        ].join('\n');
+    }
+    // 5. 消息提示（delete, edit 等）
+    if (typeof value.message === 'string') {
+        const extra = value.detail || value.output;
+        return `**${value.message}**` + (extra ? `\n\`\`\`\n${extra}\n\`\`\`` : '');
+    }
+    // 6. 兜底
+    return JSON.stringify(value, null, 2);
+}

package/lib/renderers/issue.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Issue 领域渲染器：负责 Issue 列表多标签表格、单卡详情、指派人与图片附件提示
+ */
+export declare function renderIssueMarkdown(args: any, value: any): string;

package/lib/renderers/issue.js

@@ -0,0 +1,70 @@
+import { sanitizeCell, formatStateBadge } from './common.js';
+/**
+ * Issue 领域渲染器：负责 Issue 列表多标签表格、单卡详情、指派人与图片附件提示
+ */
+export function renderIssueMarkdown(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\`\`\`` : '');
+    }
+    // 2.1 Issue 列表
+    if (Array.isArray(value.items) && args?.action === 'list') {
+        const list = value.items.filter(Boolean);
+        if (list.length === 0)
+            return '📭 当前仓库暂无匹配的 Issue。';
+        const rows = list.map((i) => {
+            const numLink = i.url ? `[#${i.number}](${i.url})` : `#${i.number}`;
+            const badge = formatStateBadge(i.state);
+            const title = sanitizeCell(i.title, 60);
+            const labels = Array.isArray(i.labels) && i.labels.length > 0
+                ? i.labels.map((l) => `\`${sanitizeCell(l.name || l, 15)}\``).join(' ')
+                : '-';
+            const author = i.author?.login ? `@${i.author.login}` : (typeof i.author === 'string' ? `@${i.author}` : '-');
+            const date = i.updatedAt ? i.updatedAt.slice(0, 10) : '-';
+            return `| ${numLink} | ${badge} | ${title} | ${labels} | ${author} | ${date} |`;
+        });
+        return [
+            `**找到 ${list.length} 个 Issue:**\n`,
+            '| 编号 | 状态 | 标题 | 标签 | 作者 | 更新日期 |',
+            '| :--- | :--- | :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 2.2 Issue View 详情
+    if (args?.action === 'view' && value.number) {
+        const link = value.url ? `[#${value.number}](${value.url})` : `#${value.number}`;
+        const badge = formatStateBadge(value.state);
+        const author = value.author?.login ? `@${value.author.login}` : '-';
+        const lines = [
+            `### ${badge} ${value.title} (${link})`,
+            `- **作者**: ${author} | **更新时间**: ${value.updatedAt?.slice(0, 16) || '-'}`,
+        ];
+        if (Array.isArray(value.labels) && value.labels.length > 0) {
+            lines.push(`- **标签**: ${value.labels.map((l) => `\`${l.name || l}\``).join(' ')}`);
+        }
+        if (Array.isArray(value.assignees) && value.assignees.length > 0) {
+            lines.push(`- **指派人**: ${value.assignees.map((a) => `@${a.login || a}`).join(' ')}`);
+        }
+        if (value.body) {
+            lines.push('\n**议题正文:**\n```markdown\n' + sanitizeCell(value.body, 300) + '\n```');
+        }
+        // 图片附件清单（view 附带 URL 清单，view_images 按需下载查看）
+        if (Array.isArray(value.images) && value.images.length > 0) {
+            lines.push(`- **📎 图片附件 (${value.images.length}):** 调用 \`github_issue(action: 'view_images', issue_number: ${value.number})\` 可下载查看`);
+        }
+        return lines.join('\n');
+    }
+    // 兜底降级
+    return JSON.stringify(value, null, 2);
+}

package/lib/renderers/label.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Label 领域渲染器：负责 GitHub Labels 列表、创建、编辑、克隆与删除的 Markdown 格式化
+ */
+export declare function renderLabelMarkdown(args: any, value: any): string;

package/lib/renderers/label.js

@@ -0,0 +1,48 @@
+import { sanitizeCell } from './common.js';
+/**
+ * Label 领域渲染器：负责 GitHub Labels 列表、创建、编辑、克隆与删除的 Markdown 格式化
+ */
+export function renderLabelMarkdown(args, value) {
+    if (!value)
+        return '无返回内容';
+    // 1. 高危操作确认拦截报告
+    if (value.status === 'AWAITING_CONFIRMATION') {
+        return [
+            `> ### ${value.warning || '⚠️ 操作确认拦截'}`,
+            `> - **影响评估**: ${value.impact || ''}`,
+            `> - **确认指引**: ${value.requiredAction || '如确认继续，请在参数中附加 \`confirm: true\` 重新调用。'}`,
+        ].join('\n');
+    }
+    if (typeof value.result === 'string')
+        return value.result;
+    // 2. 单操作消息提示（create, edit, delete, clone 等）
+    if (typeof value.message === 'string' && !value.items) {
+        const extra = value.detail || value.output;
+        return `**${value.message}**` + (extra ? `\n\`\`\`\n${extra}\n\`\`\`` : '');
+    }
+    // 3. 标签列表展示
+    if (Array.isArray(value.items)) {
+        const list = value.items.filter(Boolean);
+        if (list.length === 0) {
+            return args?.search
+                ? `📭 未检索到匹配关键词 "${args.search}" 的标签。`
+                : '📭 仓库中尚未创建任何标签。';
+        }
+        const rows = list.map((item) => {
+            const name = item.name ? `\`${sanitizeCell(item.name, 40)}\`` : '-';
+            const colorRaw = item.color ? String(item.color).replace(/^#/, '') : '';
+            const color = colorRaw ? `\`#${colorRaw.toLowerCase()}\`` : '-';
+            const desc = sanitizeCell(item.description, 60);
+            return `| ${name} | ${color} | ${desc} |`;
+        });
+        const searchHint = args?.search ? ` (过滤关键词: "${args.search}")` : '';
+        return [
+            `**仓库标签列表 (${list.length} 个)${searchHint}:**\n`,
+            '| 标签 | 颜色 | 描述 |',
+            '| :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 4. 兜底降级
+    return JSON.stringify(value, null, 2);
+}

package/lib/renderers/markdown.d.ts

@@ -1,35 +1,18 @@
 /**
- * DSH GitHub Flow - Native Markdown 格式化渲染引擎
+ * DSH GitHub Flow - Native Markdown 格式化渲染引擎门面入口
  *
- * 核心目标：
- * 1. 终结机械多行 JSON 输出，为列表和详情产出高密度 Markdown 表格与卡片；
- * 2. 节省 70%+ 的会话上下文 Token，极大加速长对话推理速度；
- * 3. 嵌入可点击超链接与直观的状态药丸 Emoji，提升人类与模型阅读体验；
- * 4. 严谨防御 Markdown 表格竖线破坏、缺失值回退与异常对象降级。
+ * 为保持向后兼容性与构建产物一致性，本入口统一 Re-export 全部领域渲染器
+ * 与通用徽章工具，各 Agent Tool 与自动化单测可无感引用。
  */
-/** 安全清洗表格单元格文本：转义竖线，压缩换行，限制最大长度 */
-export declare function sanitizeCell(text: any, maxLen?: number): string;
-/** 格式化 PR / Issue 状态药丸徽章 */
-export declare function formatStateBadge(state?: string, isDraft?: boolean): string;
-/**
- * 格式化 CI 工作流状态徽章。
- * 第二参数按调用域语义不同：run 域传 conclusion（success/failure/cancelled/skipped），
- * pr checks 域传 bucket（pass/fail/pending/skipping/cancel）——取值族不同但映射到
- * 同一组徽章；state 参数兜底（in_progress/queued 等进行中态）。
- */
-export declare function formatCiBadge(status?: string, conclusion?: string): string;
-/** 格式化合并冲突状态 */
-export declare function formatConflictBadge(status?: string): string;
-/**
- * 降级链路可见标注（runGuarded 契约的渲染兑现）。
- * 为什么必须可见：降级若是静默的，Agent 就无法感知能力边界（同一 action 在
- * 不同 gh 版本上走不同链路）；一条 blockquote 注释成本一行，换链路透明。
- */
-export declare function appendDegradedNote(value: any): string;
-export declare function renderPrMarkdown(args: any, value: any): string;
-export declare function renderIssueMarkdown(args: any, value: any): string;
-export declare function renderRunMarkdown(args: any, value: any): string;
-export declare function renderRepoMarkdown(args: any, value: any): string;
-export declare function formatReleaseBadge(isDraft?: boolean, isPrerelease?: boolean): string;
-export declare function renderReleaseMarkdown(args: any, value: any): string;
-export declare function renderSkillMarkdown(args: any, value: any): string;
+export * from './common.js';
+export * from './pr.js';
+export * from './issue.js';
+export * from './run.js';
+export * from './repo.js';
+export * from './release.js';
+export * from './skill.js';
+export * from './label.js';
+export * from './ruleset.js';
+export * from './cache.js';
+export * from './gist.js';
+export * from './status.js';