dsh-github-flow 0.3.0 → 0.5.0

package/lib/git-watcher.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Git 元数据变更事件载荷
+ */
+export interface GitChangeEvent {
+    /** 是否检测到本地 Git 元数据变动 */
+    changed?: boolean;
+    /** 触发时间戳（毫秒） */
+    at?: number;
+    /** 是否因达到长轮询上限而超时返回 */
+    timeout?: boolean;
+}
+/**
+ * Git 监听器配置项
+ */
+export interface GitWatchOptions {
+    /** 防抖时间（毫秒），默认 800ms */
+    debounceMs?: number;
+    /** 长轮询超时时间（毫秒），默认 35,000ms */
+    timeoutMs?: number;
+}
+/**
+ * 定向针对 .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 declare function watchGitMetadata(cwd: string, onTrigger: (event: GitChangeEvent) => void, options?: GitWatchOptions): () => void;

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,7 +7,17 @@ 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 { createAgentTaskTool } from './tools/agent-task.js';
+import { createDiscussionTool } from './tools/discussion.js';
+import { createProjectTool } from './tools/project.js';
+import { createCodespaceTool } from './tools/codespace.js';
 import { createHelpTool } from './tools/help.js';
+import { defaultTelemetryCollector } from './telemetry.js';
 import { registerGhCommand } from './commands/gh.js';
 import { registerApiRoutes } from './api/routes.js';
 import { UpdateChecker } from './updater.js';
@@ -83,11 +93,26 @@ export function apply(ctx, config = {}) {
     else {
         ctx.github = executor;
     }
-    // 2. 注册人类 Slash 命令 (/gh status, /gh upgrade, /gh help)
+    // 2. 注册 Cordis tools/result 事件切面（无侵入全量工具审计与降级率打点）
+    if (ctx.on && typeof ctx.on === 'function') {
+        ctx.on('tools/result', (exec, result) => {
+            try {
+                const toolName = exec?.name || exec?.tool?.name || '';
+                if (typeof toolName === 'string' && toolName.startsWith('github_')) {
+                    const args = exec?.arguments || exec?.args || {};
+                    defaultTelemetryCollector.recordCall(toolName, args, result);
+                }
+            }
+            catch {
+                // Fail-Open 非阻塞防线：严禁打点逻辑异常影响主工具调用
+            }
+        });
+    }
+    // 3. 注册人类 Slash 命令 (/gh status, /gh upgrade, /gh help)
     if (ctx.commands) {
-        registerGhCommand(ctx.commands, executor, updateChecker);
+        registerGhCommand(ctx.commands, executor, updateChecker, defaultTelemetryCollector);
     }
-    // 3. 注册 Agent 模型工具集（核心领域工具 + 元指南）
+    // 4. 注册 Agent 模型工具集（核心领域工具 + 元指南）
     if (ctx.tools) {
         ctx.tools.register(createPrTool(executor));
         ctx.tools.register(createIssueTool(executor));
@@ -97,6 +122,15 @@ 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, defaultTelemetryCollector));
+        ctx.tools.register(createAgentTaskTool(executor));
+        ctx.tools.register(createDiscussionTool(executor));
+        ctx.tools.register(createProjectTool(executor));
+        ctx.tools.register(createCodespaceTool(executor));
         ctx.tools.register(createHelpTool(executor));
     }
     // 4. 注册面向 Client 端的 WebServer HTTP 路由（如果当前环境启用了 Web UI 服务）

package/lib/renderers/agent-task.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 格式化 Agent Task 状态徽标
+ */
+export declare function formatAgentTaskStateBadge(state?: string): string;
+/**
+ * 渲染 Agent Tasks 列表表格
+ */
+export declare function renderAgentTaskList(items: any[]): string;
+/**
+ * 渲染单个 Agent Task 详情卡片
+ */
+export declare function renderAgentTaskView(task: any): string;
+/**
+ * Agent Task 领域综合渲染入口
+ */
+export declare function renderAgentTaskMarkdown(args: any, value: any): string;

package/lib/renderers/agent-task.js

@@ -0,0 +1,107 @@
+import { sanitizeCell } from './common.js';
+/**
+ * 格式化 Agent Task 状态徽标
+ */
+export function formatAgentTaskStateBadge(state) {
+    if (!state)
+        return '⚪ UNKNOWN';
+    const upper = state.toUpperCase();
+    switch (upper) {
+        case 'COMPLETED':
+        case 'SUCCESS':
+            return '🟢 COMPLETED';
+        case 'IN_PROGRESS':
+        case 'RUNNING':
+            return '🟡 RUNNING';
+        case 'FAILED':
+        case 'FAILURE':
+            return '🔴 FAILED';
+        case 'CANCELLED':
+        case 'CANCELED':
+            return '⚪ CANCELLED';
+        default:
+            return `⚪ ${upper}`;
+    }
+}
+/**
+ * 渲染 Agent Tasks 列表表格
+ */
+export function renderAgentTaskList(items) {
+    const list = items.filter(Boolean);
+    if (list.length === 0) {
+        return '📭 暂无智能体任务 (Agent Tasks)。';
+    }
+    const rows = list.map((t) => {
+        const rawId = String(t.id || '-');
+        const shortId = rawId.length > 8 ? `\`${rawId.slice(0, 8)}...\`` : `\`${rawId}\``;
+        const name = sanitizeCell(t.name || '(无描述)', 40);
+        const stateBadge = formatAgentTaskStateBadge(t.state);
+        let prCell = '-';
+        if (t.pullRequestNumber) {
+            const prText = `#${t.pullRequestNumber}`;
+            prCell = t.pullRequestUrl ? `[${prText}](${t.pullRequestUrl})` : prText;
+        }
+        const created = t.createdAt ? t.createdAt.split('T')[0] : '-';
+        return `| ${shortId} | ${name} | ${stateBadge} | ${prCell} | ${created} |`;
+    });
+    return [
+        `**智能体任务列表 (${list.length} 条):**\n`,
+        '| 任务 ID | 描述 | 状态 | 关联 PR | 创建日期 |',
+        '| :--- | :--- | :--- | :--- | :--- |',
+        ...rows,
+    ].join('\n');
+}
+/**
+ * 渲染单个 Agent Task 详情卡片
+ */
+export function renderAgentTaskView(task) {
+    if (!task || typeof task !== 'object') {
+        return '无任务详情数据';
+    }
+    const name = task.name || '(未命名任务)';
+    const stateBadge = formatAgentTaskStateBadge(task.state);
+    const repo = task.repository ? `[${task.repository}](https://github.com/${task.repository})` : '-';
+    const user = task.user?.login || task.user || '-';
+    const created = task.createdAt || '-';
+    const completed = task.completedAt || '-';
+    const lines = [
+        `### 🤖 Agent Task: ${name}\n`,
+        `- **任务 ID**: \`${task.id || '-'}\``,
+        `- **状态**: ${stateBadge}`,
+        `- **目标仓库**: ${repo}`,
+        `- **分派用户**: @${user}`,
+        `- **创建时间**: ${created}`,
+        `- **完成时间**: ${completed}`,
+    ];
+    if (task.pullRequestNumber) {
+        const prTitle = task.pullRequestTitle ? ` - ${task.pullRequestTitle}` : '';
+        const prLink = task.pullRequestUrl
+            ? `[#${task.pullRequestNumber}${prTitle}](${task.pullRequestUrl})`
+            : `#${task.pullRequestNumber}${prTitle}`;
+        lines.push(`- **关联 PR**: ${prLink} (${task.pullRequestState || 'OPEN'})`);
+    }
+    if (task.logs || task.log) {
+        lines.push('\n**会话日志记录:**', '```text', String(task.logs || task.log).trim(), '```');
+    }
+    return lines.join('\n');
+}
+/**
+ * Agent Task 领域综合渲染入口
+ */
+export function renderAgentTaskMarkdown(args, value) {
+    if (!value)
+        return '无返回内容';
+    if (typeof value.result === 'string')
+        return value.result;
+    if (typeof value.message === 'string' && !value.items) {
+        const extra = value.detail || value.output || value.url;
+        return `**${value.message}**` + (extra ? `\n\`\`\`\n${extra}\n\`\`\`` : '');
+    }
+    if (Array.isArray(value.items) && args?.action === 'list') {
+        return renderAgentTaskList(value.items);
+    }
+    if (args?.action === 'view' || value.id) {
+        return renderAgentTaskView(value);
+    }
+    return JSON.stringify(value, null, 2);
+}

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/codespace.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 格式化 Codespace 状态徽标
+ */
+export declare function formatCodespaceStateBadge(state?: string): string;
+/**
+ * 渲染 Codespaces 列表表格
+ */
+export declare function renderCodespaceList(items: any[]): string;
+/**
+ * 渲染单个 Codespace 详情卡片
+ */
+export declare function renderCodespaceView(cs: any): string;
+/**
+ * Codespace 领域综合渲染入口
+ */
+export declare function renderCodespaceMarkdown(args: any, value: any): string;

package/lib/renderers/codespace.js

@@ -0,0 +1,103 @@
+import { sanitizeCell } from './common.js';
+import { renderScopeRequiredMarkdown } from './project.js';
+/**
+ * 格式化 Codespace 状态徽标
+ */
+export function formatCodespaceStateBadge(state) {
+    if (!state)
+        return '⚪ UNKNOWN';
+    const lower = state.toLowerCase();
+    if (lower === 'available')
+        return '🟢 AVAILABLE';
+    if (lower === 'shutdown')
+        return '⚪ SHUTDOWN';
+    if (lower.includes('start') || lower.includes('rebuild'))
+        return '🟡 STARTING';
+    if (lower.includes('updat') || lower.includes('export'))
+        return '🟡 BUSY';
+    return `⚪ ${state.toUpperCase()}`;
+}
+/**
+ * 渲染 Codespaces 列表表格
+ */
+export function renderCodespaceList(items) {
+    const list = items.filter(Boolean);
+    if (list.length === 0) {
+        return '📭 暂无云端开发环境 (Codespaces)。';
+    }
+    const rows = list.map((cs) => {
+        const name = `\`${sanitizeCell(cs.name || '-', 25)}\``;
+        const displayName = sanitizeCell(cs.displayName || cs.name || '-', 25);
+        const repo = cs.repository ? `[${cs.repository}](https://github.com/${cs.repository})` : '-';
+        const stateBadge = formatCodespaceStateBadge(cs.state);
+        const machine = sanitizeCell(cs.machineDisplayName || cs.machineName || '-', 20);
+        const lastUsed = cs.lastUsedAt ? cs.lastUsedAt.split('T')[0] : '-';
+        return `| ${name} | ${displayName} | ${repo} | ${stateBadge} | ${machine} | ${lastUsed} |`;
+    });
+    return [
+        `**云端开发环境列表 (${list.length} 台):**\n`,
+        '| 实例标识 | 显示名称 | 关联仓库 | 运行状态 | 机器规格 | 上次使用 |',
+        '| :--- | :--- | :--- | :--- | :--- | :--- |',
+        ...rows,
+    ].join('\n');
+}
+/**
+ * 渲染单个 Codespace 详情卡片
+ */
+export function renderCodespaceView(cs) {
+    if (!cs || typeof cs !== 'object') {
+        return '无云端环境详情数据';
+    }
+    const name = cs.displayName || cs.name || '未命名实例';
+    const stateBadge = formatCodespaceStateBadge(cs.state);
+    const repo = cs.repository ? `[${cs.repository}](https://github.com/${cs.repository})` : '-';
+    const owner = cs.owner || cs.billableOwner || '-';
+    const machine = cs.machineDisplayName || cs.machineName || '-';
+    const created = cs.createdAt || '-';
+    const lastUsed = cs.lastUsedAt || '-';
+    const lines = [
+        `### ☁️ Codespace: ${name}\n`,
+        `- **实例标识**: \`${cs.name || '-'}\``,
+        `- **运行状态**: ${stateBadge}`,
+        `- **关联仓库**: ${repo}`,
+        `- **所有者**: @${owner}`,
+        `- **机器规格**: ${machine}`,
+        `- **空闲停机**: ${cs.idleTimeoutMinutes ? `${cs.idleTimeoutMinutes} 分钟` : '默认'}`,
+        `- **创建时间**: ${created}`,
+        `- **上次活跃**: ${lastUsed}`,
+    ];
+    if (cs.devcontainerPath) {
+        lines.push(`- **容器配置**: \`${cs.devcontainerPath}\``);
+    }
+    return lines.join('\n');
+}
+/**
+ * Codespace 领域综合渲染入口
+ */
+export function renderCodespaceMarkdown(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) {
+        const extra = value.detail || value.output;
+        return `**${value.message}**` + (extra ? `\n\`\`\`\n${extra}\n\`\`\`` : '');
+    }
+    if (Array.isArray(value.items) && args?.action === 'list') {
+        return renderCodespaceList(value.items);
+    }
+    if (args?.action === 'view' || value.name) {
+        return renderCodespaceView(value);
+    }
+    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/discussion.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 格式化 Discussion 状态徽标
+ */
+export declare function formatDiscussionStateBadge(state?: string, answered?: boolean, closed?: boolean): string;
+/**
+ * 渲染 Discussion 列表表格
+ */
+export declare function renderDiscussionList(items: any[]): string;
+/**
+ * 渲染单个 Discussion 详情卡片
+ */
+export declare function renderDiscussionView(d: any): string;
+/**
+ * Discussion 领域综合渲染入口
+ */
+export declare function renderDiscussionMarkdown(args: any, value: any): string;